Help: Clarify behavior of INHERITED properties

Fixes: #17839

1 files changed, 18 insertions, 4 deletions

diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst
index 873c6ca..da2631c 100644
--- a/Help/command/define_property.rst
+++ b/Help/command/define_property.rst
@@ -34,10 +34,24 @@ actual scope needs to be given; only the kind of scope is important.
 The required ``PROPERTY`` option is immediately followed by the name of
 the property being defined.
 
-If the ``INHERITED`` option then the :command:`get_property` command will
-chain up to the next higher scope when the requested property is not set
-in the scope given to the command. ``DIRECTORY`` scope chains to
-``GLOBAL``. ``TARGET``, ``SOURCE``, and ``TEST`` chain to ``DIRECTORY``.
+If the ``INHERITED`` option is given, then the :command:`get_property` command
+will chain up to the next higher scope when the requested property is not set
+in the scope given to the command.
+
+* ``DIRECTORY`` scope chains to its parent directory's scope, continuing the
+  walk up parent directories until a directory has the property set or there
+  are no more parents.  If still not found at the top level directory, it
+  chains to the ``GLOBAL`` scope.
+* ``TARGET``, ``SOURCE`` and ``TEST`` properties chain to ``DIRECTORY`` scope,
+  including further chaining up the directories, etc. as needed.
+
+Note that this scope chaining behavior only applies to calls to
+:command:`get_property`, :command:`get_directory_property`,
+:command:`get_target_property`, :command:`get_source_file_property` and
+:command:`get_test_property`.  There is no inheriting behavior when *setting*
+properties, so using ``APPEND`` or ``APPEND_STRING`` with the
+:command:`set_property` command will not consider inherited values when working
+out the contents to append to.
 
 The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are followed by strings to be
 associated with the property as its brief and full documentation.