Help: Improve ADDITIONAL_CLEAN_FILES documentation

Extend the `ADDITIONAL_CLEAN_FILES' target and directory property
documentation.

Fixes: #19341

2 files changed, 22 insertions, 10 deletions

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.