Help: Improve grammar and wording for cmake_parse_arguments
diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst index 70dbeeb..746e1f1 100644 --- a/Help/command/cmake_parse_arguments.rst +++ b/Help/command/cmake_parse_arguments.rst
@@ -20,48 +20,49 @@ and defines a set of variables which hold the values of the respective options. -The first signature reads processes arguments passed in the ``<args>...``. +The first signature reads arguments passed in the ``<args>...``. This may be used in either a :command:`macro` or a :command:`function`. .. versionadded:: 3.7 The ``PARSE_ARGV`` signature is only for use in a :command:`function` - body. In this case the arguments that are parsed come from the + body. In this case, the arguments that are parsed come from the ``ARGV#`` variables of the calling function. The parsing starts with the ``<N>``-th argument, where ``<N>`` is an unsigned integer. This allows for the values to have special characters like ``;`` in them. -The ``<options>`` argument contains all options for the respective macro, -i.e. keywords which can be used when calling the macro without any value -following, like e.g. the ``OPTIONAL`` keyword of the :command:`install` -command. +The ``<options>`` argument contains all options for the respective function +or macro. These are keywords that have no value following them, like the +``OPTIONAL`` keyword of the :command:`install` command. -The ``<one_value_keywords>`` argument contains all keywords for this macro -which are followed by one value, like e.g. ``DESTINATION`` keyword of the -:command:`install` command. +The ``<one_value_keywords>`` argument contains all keywords for this function +or macro which are followed by one value, like the ``DESTINATION`` keyword of +the :command:`install` command. The ``<multi_value_keywords>`` argument contains all keywords for this -macro which can be followed by more than one value, like e.g. the +function or macro which can be followed by more than one value, like the ``TARGETS`` or ``FILES`` keywords of the :command:`install` command. .. versionchanged:: 3.5 - All keywords shall be unique. I.e. every keyword shall only be specified - once in either ``<options>``, ``<one_value_keywords>`` or + All keywords must be unique. Each keyword can only be specified + once in any of the ``<options>``, ``<one_value_keywords>``, or ``<multi_value_keywords>``. A warning will be emitted if uniqueness is violated. When done, ``cmake_parse_arguments`` will consider for each of the -keywords listed in ``<options>``, ``<one_value_keywords>`` and -``<multi_value_keywords>`` a variable composed of the given ``<prefix>`` -followed by ``"_"`` and the name of the respective keyword. These -variables will then hold the respective value from the argument list -or be undefined if the associated option could not be found. -For the ``<options>`` keywords, these will always be defined, -to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not. +keywords listed in ``<options>``, ``<one_value_keywords>``, and +``<multi_value_keywords>``, a variable composed of the given ``<prefix>`` +followed by ``"_"`` and the name of the respective keyword. For +``<one_value_keywords>`` and ``<multi_value_keywords>``, these variables +will then hold the respective value(s) from the argument list, or be undefined +if the associated keyword was not given (policy :policy:`CMP0174` can also +affect the behavior for ``<one_value_keywords>``). For the ``<options>`` +keywords, these variables will always be defined, and they will be set to +``TRUE`` if the keyword is present, or ``FALSE`` if it is not. All remaining arguments are collected in a variable ``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all arguments were recognized. This can be checked afterwards to see -whether your macro was called with unrecognized parameters. +whether your macro or function was called with unrecognized parameters. .. versionadded:: 3.15 ``<one_value_keywords>`` and ``<multi_value_keywords>`` that were given no @@ -96,7 +97,7 @@ my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS) -After the ``cmake_parse_arguments`` call the macro will have set or undefined +After the ``cmake_parse_arguments`` call, the macro will have set or undefined the following variables:: MY_INSTALL_OPTIONAL = TRUE @@ -111,14 +112,14 @@ You can then continue and process these variables. -Keywords terminate lists of values, e.g. if directly after a -``one_value_keyword`` another recognized keyword follows, this is -interpreted as the beginning of the new option. E.g. +Keywords terminate lists of values. If a keyword is given directly after a +``<one_value_keyword>``, that preceding ``<one_value_keyword>`` receives no +value and the keyword is added to the ``<prefix>_KEYWORDS_MISSING_VALUES`` +variable. For the above example, the call ``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in -``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL`` -is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added -to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will -therefore be set to ``TRUE``. +``MY_INSTALL_OPTIONAL`` being set to ``TRUE`` and ``MY_INSTALL_DESTINATION`` +being unset. The ``MY_INSTALL_KEYWORDS_MISSING_VALUES`` variable would hold +the value ``DESTINATION``. See Also ^^^^^^^^