Merge topic 'generated-byproducts-docs' into release-3.17

3eb2b62d21 Help: Expand discussion of GENERATED / BYPRODUCTS
1853c7f571 Help: Add missing word in AUTOGEN_TARGET_DEPENDS.rst

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !4472

4 files changed, 30 insertions, 11 deletions

diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst
index 69d6e9aed2..92797480a1 100644
--- a/Help/command/add_custom_command.rst
+++ b/Help/command/add_custom_command.rst
@@ -68,6 +68,9 @@ The options are:
   order-only dependencies to ensure the byproducts will be
   available before their dependents build.
 
+  The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other
+  :prop_sf:`GENERATED` files during ``make clean``.
+
 ``COMMAND``
   Specify the command-line(s) to execute at build time.
   If more than one ``COMMAND`` is specified they will be executed in order,
diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst
index 2d5f5f0818..56ab414ddb 100644
--- a/Help/command/add_custom_target.rst
+++ b/Help/command/add_custom_target.rst
@@ -49,6 +49,9 @@ The options are:
   order-only dependencies to ensure the byproducts will be
   available before their dependents build.
 
+  The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other
+  :prop_sf:`GENERATED` files during ``make clean``.
+
 ``COMMAND``
   Specify the command-line(s) to execute at build time.
   If more than one ``COMMAND`` is specified they will be executed in order,
diff --git a/Help/prop_sf/GENERATED.rst b/Help/prop_sf/GENERATED.rst
index d430ee264f..48ff70c7b3 100644
--- a/Help/prop_sf/GENERATED.rst
+++ b/Help/prop_sf/GENERATED.rst
@@ -4,16 +4,29 @@ GENERATED
 Is this source file generated as part of the build or CMake process.
 
 Tells the internal CMake engine that a source file is generated by an outside
-process such as another build step, or the execution of CMake itself. This
-information is then used to exempt the file from any existence or validity
-checks. Generated files are created by the execution of commands such as
-:command:`add_custom_command` and :command:`file(GENERATE)`.
-
-When a generated file created by an :command:`add_custom_command` command
-is explicitly listed as a source file for any target in the same
-directory scope (which usually means the same ``CMakeLists.txt`` file),
-CMake will automatically create a dependency to make sure the file is
-generated before building that target.
+process such as another build step, or the execution of CMake itself.
+This information is then used to exempt the file from any existence or
+validity checks.
+
+Any file that is
+
+- created by the execution of commands such as
+  :command:`add_custom_command` and :command:`file(GENERATE)`
+- listed as one of the ``BYPRODUCTS`` of an :command:`add_custom_command`
+  or :command:`add_custom_target` command, or
+- created by a CMake ``AUTOGEN`` operation such as :prop_tgt:`AUTOMOC`,
+  :prop_tgt:`AUTORCC`, or :prop_tgt:`AUTOUIC`
+
+will be marked with the ``GENERATED`` property.
+
+When a generated file created as the ``OUTPUT`` of an
+:command:`add_custom_command` command is explicitly listed as a source file
+for any target in the same directory scope (which usually means the same
+``CMakeLists.txt`` file), CMake will automatically create a dependency to
+make sure the file is generated before building that target.
+
+The :ref:`Makefile Generators` will remove ``GENERATED`` files during
+``make clean``.
 
 Generated sources may be hidden in some IDE tools, while in others they might
 be shown. For the special case of sources generated by CMake's :prop_tgt:`AUTOMOC`
diff --git a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst
index d5c5e147d4..92b52a3e18 100644
--- a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst
+++ b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst
@@ -33,4 +33,4 @@ If :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` depends on a file that is either
   :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` or :policy:`CMP0071` or
 - a file that isn't in the origin target's sources
 
-it must added to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`.
+it must be added to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`.