Merge topic 'docs/setdirproprs'

6d8cabe8d4 Help: Clarify INCLUDE_DIRECTORIES directory property behavior
7b9d8ce168 Help: Clarify wording of set_directory_properties docs

Acked-by: Kitware Robot <[email protected]>
Merge-request: !2337

Help/command/set_directory_properties.rst

@@ -1,12 +1,11 @@
 set_directory_properties
 ------------------------
 
-Set a property of the directory.
+Set properties of the current directory and subdirectories in key-value pairs.
 
 ::
 
   set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
 
-Set a property for the current directory and subdirectories. See
-:ref:`Directory Properties` for the list of properties known
-to CMake.
+See :ref:`Directory Properties` for the list of properties known to CMake
+and their individual documentation for the behavior of each property.

Help/prop_dir/INCLUDE_DIRECTORIES.rst

@@ -11,11 +11,17 @@ target property, which is used by the generators to set the include
 directories for the compiler.
 
 In addition to accepting values from that command, values may be set
-directly on any directory using the :command:`set_property` command.  A
-directory gets its initial value from its parent directory if it has one.
-The initial value of the :prop_tgt:`INCLUDE_DIRECTORIES` target property
+directly on any directory using the :command:`set_property` command, and can be
+set on the current directory using the :command:`set_directory_properties`
+command.  A directory gets its initial value from its parent directory if it has
+one.  The initial value of the :prop_tgt:`INCLUDE_DIRECTORIES` target property
 comes from the value of this property.  Both directory and target property
 values are adjusted by calls to the :command:`include_directories` command.
+Calls to :command:`set_property` or :command:`set_directory_properties`,
+however, will update the directory property value without updating target
+property values.  Therefore direct property updates must be made before
+calls to :command:`add_executable` or :command:`add_library` for targets
+they are meant to affect.
 
 The target property values are used by the generators to set the
 include paths for the compiler.