Merge topic 'doc-source-prop-dir-options'

0bdb1a77d1 Help: Clarify wording of dir-related source property options

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !5000

4 files changed, 84 insertions, 56 deletions

diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst
index 123cd45..0602518 100644
--- a/Help/command/get_property.rst
+++ b/Help/command/get_property.rst
@@ -10,7 +10,7 @@ Get a property.
                 DIRECTORY [<dir>]  |
                 TARGET    <target> |
                 SOURCE    <source> |
-                          [TARGET_DIRECTORY <target> | DIRECTORY <dir>] |
+                          [DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
                 INSTALL   <file>   |
                 TEST      <test>   |
                 CACHE     <entry>  |
@@ -31,18 +31,36 @@ It must be one of the following:
   Scope defaults to the current directory but another
   directory (already processed by CMake) may be named by the
   full or relative path ``<dir>``.
+  See also the :command:`get_directory_property` command.
 
 ``TARGET``
   Scope must name one existing target.
+  See also the :command:`get_target_property` command.
 
 ``SOURCE``
-  Scope must name one source file.
+  Scope must name one source file.  By default, the source file's property
+  will be read from the current source directory's scope, but this can be
+  overridden with one of the following sub-options:
+
+  ``DIRECTORY <dir>``
+    The source file property will be read from the ``<dir>`` directory's
+    scope.  CMake must already know about that source directory, either by
+    having added it through a call to :command:`add_subdirectory` or ``<dir>``
+    being the top level source directory.  Relative paths are treated as
+    relative to the current source directory.
+
+  ``TARGET_DIRECTORY <target>``
+    The source file property will be read from the directory scope in which
+    ``<target>`` was created (``<target>`` must therefore already exist).
+
+  See also the :command:`get_source_file_property` command.
 
 ``INSTALL``
   Scope must name one installed file path.
 
 ``TEST``
   Scope must name one existing test.
+  See also the :command:`get_test_property` command.
 
 ``CACHE``
   Scope must name one cache entry.
@@ -50,15 +68,6 @@ It must be one of the following:
 ``VARIABLE``
   Scope is unique and does not accept a name.
 
-In the ``SOURCE`` case, the queried source file scope can be changed by
-specifying one of the additional options: ``DIRECTORY`` or ``TARGET_DIRECTORY``.
-
-``DIRECTORY`` takes a path to a processed directory, and the source file property
-will be read from that directory scope.
-
-``TARGET_DIRECTORY`` takes the name of an existing target. The source file
-property will be read from this target's directory scope.
-
 The required ``PROPERTY`` option is immediately followed by the name of
 the property to get.  If the property is not set an empty value is
 returned, although some properties support inheriting from a parent scope
diff --git a/Help/command/get_source_file_property.rst b/Help/command/get_source_file_property.rst
index 1060251..76ed776 100644
--- a/Help/command/get_source_file_property.rst
+++ b/Help/command/get_source_file_property.rst
@@ -5,24 +5,33 @@ Get a property for a source file.
 
 .. code-block:: cmake
 
-  get_source_file_property(VAR file [TARGET_DIRECTORY <target> | DIRECTORY <dir>] property)
+  get_source_file_property(<variable> <file>
+                           [DIRECTORY <dir> | TARGET_DIRECTORY <target>]
+                           <property>)
 
 Gets a property from a source file.  The value of the property is
-stored in the variable ``VAR``.  If the source property is not found, the
-behavior depends on whether it has been defined to be an ``INHERITED`` property
-or not (see :command:`define_property`).  Non-inherited properties will set
-``VAR`` to "NOTFOUND", whereas inherited properties will search the relevant
-parent scope as described for the :command:`define_property` command and
-if still unable to find the property, ``VAR`` will be set to an empty string.
-
-The queried source file scope can be changed by specifying one of the
-additional options: ``DIRECTORY`` or ``TARGET_DIRECTORY``.
-
-``DIRECTORY`` takes a path to a processed directory, and the source file property
-will be read from that directory scope.
-
-``TARGET_DIRECTORY`` takes the name of an existing target. The source file
-property will be read from this target's directory scope.
+stored in the specified ``<variable>``.  If the source property is not found,
+the behavior depends on whether it has been defined to be an ``INHERITED``
+property or not (see :command:`define_property`).  Non-inherited properties
+will set ``variable`` to ``NOTFOUND``, whereas inherited properties will search
+the relevant parent scope as described for the :command:`define_property`
+command and if still unable to find the property, ``variable`` will be set to
+an empty string.
+
+By default, the source file's property will be read from the current source
+directory's scope, but this can be overridden with one of the following
+sub-options:
+
+``DIRECTORY <dir>``
+  The source file property will be read from the ``<dir>`` directory's
+  scope.  CMake must already know about that source directory, either by
+  having added it through a call to :command:`add_subdirectory` or ``<dir>``
+  being the top level source directory.  Relative paths are treated as
+  relative to the current source directory.
+
+``TARGET_DIRECTORY <target>``
+  The source file property will be read from the directory scope in which
+  ``<target>`` was created (``<target>`` must therefore already exist).
 
 Use :command:`set_source_files_properties` to set property values.  Source
 file properties usually control how the file is built. One property that is
diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst
index ccbd635..93c2d9c 100644
--- a/Help/command/set_property.rst
+++ b/Help/command/set_property.rst
@@ -9,13 +9,13 @@ Set a named property in a given scope.
                 DIRECTORY [<dir>]           |
                 TARGET    [<target1> ...]   |
                 SOURCE    [<src1> ...]
-                          [TARGET_DIRECTORY <target1> ...]
-                          [DIRECTORY <dir1> ...] |
+                          [DIRECTORY <dirs> ...] |
+                          [TARGET_DIRECTORY <targets> ...]
                 INSTALL   [<file1> ...]     |
                 TEST      [<test1> ...]     |
                 CACHE     [<entry1> ...]    >
                [APPEND] [APPEND_STRING]
-               PROPERTY <name> [value1 ...])
+               PROPERTY <name> [<value1> ...])
 
 Sets one property on zero or more objects of a scope.
 
@@ -35,17 +35,23 @@ It must be one of the following:
   See also the :command:`set_target_properties` command.
 
 ``SOURCE``
-  Scope may name zero or more source files.  Note that source
-  file properties are by default visible only to targets added in the same
-  directory (``CMakeLists.txt``).
-  The file properties can be made visible in a different directory by specifying
-  one or both of the additional options: ``TARGET_DIRECTORY`` and ``DIRECTORY``.
+  Scope may name zero or more source files.  By default, source file properties
+  are only visible to targets added in the same directory (``CMakeLists.txt``).
+  Visibility can be set in other directory scopes using one or both of the
+  following sub-options:
+
+  ``DIRECTORY <dirs>...``
+    The source file property will be set in each of the ``<dirs>``
+    directories' scopes.  CMake must already know about each of these
+    source directories, either by having added them through a call to
+    :command:`add_subdirectory` or it being the top level source directory.
+    Relative paths are treated as relative to the current source directory.
+
+  ``TARGET_DIRECTORY <targets>...``
+    The source file property will be set in each of the directory scopes
+    where any of the specified ``<targets>`` were created (the ``<targets>``
+    must therefore already exist).
 
-  ``DIRECTORY`` takes a list of processed directories paths, and sets the file
-  properties in those directory scopes.
-
-  ``TARGET_DIRECTORY`` takes a list of existing targets. The file
-  properties will be set in these targets' directory scopes.
   See also the :command:`set_source_files_properties` command.
 
 ``INSTALL``
diff --git a/Help/command/set_source_files_properties.rst b/Help/command/set_source_files_properties.rst
index 59d5ba3..9558b40 100644
--- a/Help/command/set_source_files_properties.rst
+++ b/Help/command/set_source_files_properties.rst
@@ -5,29 +5,33 @@ Source files can have properties that affect how they are built.
 
 .. code-block:: cmake
 
-  set_source_files_properties([file1 [file2 [...]]]
-                              [TARGET_DIRECTORY <target1> ...]
-                              [DIRECTORY <dir1> ...]
-                              PROPERTIES prop1 value1
-                              [prop2 value2 [...]])
+  set_source_files_properties(<files> ...
+                              [DIRECTORY <dirs> ...]
+                              [TARGET_DIRECTORY <targets> ...]
+                              PROPERTIES <prop1> <value1>
+                              [<prop2> <value2>] ...)
 
 Sets properties associated with source files using a key/value paired
 list.
 
-Note that source file properties are by default visible only to
-targets added in the same directory (``CMakeLists.txt``).
+By default, source file properties are only visible to targets added in the
+same directory (``CMakeLists.txt``).  Visibility can be set in other directory
+scopes using one or both of the following options:
 
-The file properties can be made visible in a different directory by specifying
-one or both of the additional options: ``TARGET_DIRECTORY`` and ``DIRECTORY``.
+``DIRECTORY <dirs>...``
+  The source file properties will be set in each of the ``<dirs>``
+  directories' scopes.  CMake must already know about each of these
+  source directories, either by having added them through a call to
+  :command:`add_subdirectory` or it being the top level source directory.
+  Relative paths are treated as relative to the current source directory.
 
-``DIRECTORY`` takes a list of processed directories paths, and sets the file
-properties in those directory scopes.
-
-``TARGET_DIRECTORY`` takes a list of existing targets. The file
-properties will be set in these targets' directory scopes.
+``TARGET_DIRECTORY <targets>...``
+  The source file properties will be set in each of the directory scopes
+  where any of the specified ``<targets>`` were created (the ``<targets>``
+  must therefore already exist).
 
+Use :command:`get_source_file_property` to get property values.
 See also the :command:`set_property(SOURCE)` command.
 
 See :ref:`Source File Properties` for the list of properties known
-to CMake.  Source file properties are visible only to targets added
-in the same directory (``CMakeLists.txt``).
+to CMake.