Help: Document property redefinition semantics

Add a section to the `define_property()` documentation which
details the behavior when attempting to redefine an existing
property. (The command is silently ignored.)

Provide an example using `get_property()` to examine a property
definition created with `define_property()`.

1 files changed, 36 insertions, 0 deletions

diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst
index 5278e30..06f2823 100644
--- a/Help/command/define_property.rst
+++ b/Help/command/define_property.rst
@@ -74,6 +74,42 @@ project via corresponding options to the :command:`get_property` command.
   underscore. It is recommended that the property name have a prefix specific
   to the project.
 
+Property Redefinition
+^^^^^^^^^^^^^^^^^^^^^
+
+Once a property is defined for a particular type of scope, it cannot be
+redefined. Attempts to redefine an existing property by calling
+:command:`define_property` with the same scope type and property name
+will be silently ignored. Defining the same property name for two different
+kinds of scope is valid.
+
+:command:`get_property` can be used to determine whether a property is
+already defined for a particular kind of scope, and if so, to examine its
+definition. For example:
+
+.. code-block:: cmake
+
+  # Initial definition
+  define_property(TARGET PROPERTY MY_NEW_PROP
+    BRIEF_DOCS "My new custom property"
+  )
+
+  # Later examination
+  get_property(my_new_prop_exists
+    TARGET NONE
+    PROPERTY MY_NEW_PROP
+    DEFINED
+  )
+
+  if(my_new_prop_exists)
+    get_property(my_new_prop_docs
+      TARGET NONE
+      PROPERTY MY_NEW_PROP
+      BRIEF_DOCS
+    )
+    # ${my_new_prop_docs} is now set to "My new custom property"
+  endif()
+
 See Also
 ^^^^^^^^