Merge topic 'cleanup-define_property'

87c3b5e421 define_property(): Only test prefix if INITIALIZE_FROM_VARIABLE is given
9b50f221f6 Help: Update the main purpose of define_property()
e993e2c52c Help: Clean up INITIALIZE_FROM_VARIABLE define_property() option

Acked-by: Kitware Robot <kwrobot@kitware.com>
Tested-by: buildbot <buildbot@kitware.com>
Acked-by: Kyle Edwards <kyle.edwards@kitware.com>
Merge-request: !7090

1 files changed, 15 insertions, 11 deletions

diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst
index cd75dea..c882347 100644
--- a/Help/command/define_property.rst
+++ b/Help/command/define_property.rst
@@ -13,11 +13,13 @@ Define and document custom properties.
                    [INITIALIZE_FROM_VARIABLE <variable>])
 
 Defines one property in a scope for use with the :command:`set_property` and
-:command:`get_property` commands.  This is primarily useful to associate
-documentation with property names that may be retrieved with the
-:command:`get_property` command. The first argument determines the kind of
-scope in which the property should be used.  It must be one of the
-following:
+:command:`get_property` commands. It is mainly useful for defining the way
+a property is initialized or inherited. Historically, the command also
+associated documentation with a property, but that is no longer considered a
+primary use case.
+
+The first argument determines the kind of scope in which the property should
+be used.  It must be one of the following:
 
 ::
 
@@ -56,14 +58,16 @@ 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.
-Corresponding options to the :command:`get_property` command will retrieve
-the documentation.
+CMake does not use this documentation other than making it available to the
+project via corresponding options to the :command:`get_property` command.
 
 .. versionchanged:: 3.23
 
   The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are optional.
 
-The ``INITIALIZE_FROM_VARIABLE`` option is followed by the name of a variable
-from which to initialize the property. The variable name must end with the
-property name, must have a prefix before the property name, and must not begin
-with ``CMAKE_`` or ``_CMAKE_``.
+.. versionadded:: 3.23
+
+  The ``INITIALIZE_FROM_VARIABLE`` option specifies a variable from which the
+  property should be initialized. It can only be used with target properties.
+  The ``<variable>`` name must end with the property name, must have a prefix
+  before the property name, and must not begin with ``CMAKE_`` or ``_CMAKE_``.