Merge branch 'additional_clean_files_help' into release-3.15

Merge-request: !3428

3 files changed, 23 insertions, 11 deletions

diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 25aab8d..77b1ae8 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -62,7 +62,6 @@ Properties on Directories
    :maxdepth: 1
 
    /prop_dir/ADDITIONAL_CLEAN_FILES
-   /prop_dir/ADDITIONAL_MAKE_CLEAN_FILES
    /prop_dir/BINARY_DIR
    /prop_dir/BUILDSYSTEM_TARGETS
    /prop_dir/CACHE_VARIABLES
@@ -505,6 +504,7 @@ Deprecated Properties on Directories
 .. toctree::
    :maxdepth: 1
 
+   /prop_dir/ADDITIONAL_MAKE_CLEAN_FILES
    /prop_dir/COMPILE_DEFINITIONS_CONFIG
    /prop_dir/TEST_INCLUDE_FILE
 
diff --git a/Help/prop_dir/ADDITIONAL_CLEAN_FILES.rst b/Help/prop_dir/ADDITIONAL_CLEAN_FILES.rst
index 54a78ef..051d22a 100644
--- a/Help/prop_dir/ADDITIONAL_CLEAN_FILES.rst
+++ b/Help/prop_dir/ADDITIONAL_CLEAN_FILES.rst
@@ -1,16 +1,21 @@
 ADDITIONAL_CLEAN_FILES
 ----------------------
 
-Additional files to remove during the clean stage.
+A :ref:`;-list <CMake Language Lists>` of files or directories that will be
+removed as a part of the global ``clean`` target.  It is useful for
+specifying generated files or directories that are used by multiple targets
+or by CMake itself, or that are generated in ways which cannot be captured as
+outputs or byproducts of custom commands.
 
-A :ref:`;-list <CMake Language Lists>` of files that will be removed as a
-part of the ``clean`` target.
+If an additional clean file is specific to a single target only, then the
+:prop_tgt:`ADDITIONAL_CLEAN_FILES` target property would usually be a better
+choice than this directory property.
 
 Relative paths are allowed and are interpreted relative to the
 current binary directory.
 
-Arguments to :prop_dir:`ADDITIONAL_CLEAN_FILES` may use
+Contents of ``ADDITIONAL_CLEAN_FILES`` may use
 :manual:`generator expressions <cmake-generator-expressions(7)>`.
 
 This property only works for the :generator:`Ninja` and the Makefile
-generators.  It is ignored on other generators.
+generators.  It is ignored by other generators.
diff --git a/Help/prop_tgt/ADDITIONAL_CLEAN_FILES.rst b/Help/prop_tgt/ADDITIONAL_CLEAN_FILES.rst
index 856bb38..3b9d965 100644
--- a/Help/prop_tgt/ADDITIONAL_CLEAN_FILES.rst
+++ b/Help/prop_tgt/ADDITIONAL_CLEAN_FILES.rst
@@ -1,16 +1,23 @@
 ADDITIONAL_CLEAN_FILES
 ----------------------
 
-Additional files to remove during the clean stage.
+A :ref:`;-list <CMake Language Lists>` of files or directories that will be
+removed as a part of the global ``clean`` target.  It can be used to specify
+files and directories that are generated as part of building the target or
+that are directly associated with the target in some way (e.g. created as a
+result of running the target).
 
-A :ref:`;-list <CMake Language Lists>` of files that will be removed as a
-part of the ``clean`` target.
+For custom targets, if such files can be captured as outputs or byproducts
+instead, then that should be preferred over adding them to this property.
+If an additional clean file is used by multiple targets or isn't
+target-specific, then the :prop_dir:`ADDITIONAL_CLEAN_FILES` directory
+property may be the more appropriate property to use.
 
 Relative paths are allowed and are interpreted relative to the
 current binary directory.
 
-Arguments to :prop_tgt:`ADDITIONAL_CLEAN_FILES` may use
+Contents of ``ADDITIONAL_CLEAN_FILES`` may use
 :manual:`generator expressions <cmake-generator-expressions(7)>`.
 
 This property only works for the :generator:`Ninja` and the Makefile
-generators.  It is ignored on other generators.
+generators.  It is ignored by other generators.