Help: Update the main purpose of define_property()

The BRIEF_DOCS and FULL_DOCS are remnants from before the
Sphinx-based documentation when CMake's internal structures
for defining properties included fields for their documentation.
They are no longer mandatory for define_property() and haven't
been in practical use for some time. The main use of the command
has evolved to now be more about how to initialize and inherit
properties, so update the docs to reflect that change in focus.

Issue: #20698

1 files changed, 9 insertions, 7 deletions

diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst
index 82d6a0a..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,8 +58,8 @@ 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