Help: Improve ADDITIONAL_CLEAN_FILES documentation

Extend the `ADDITIONAL_CLEAN_FILES' target and directory property
documentation.

Fixes: #19341

1 files changed, 10 insertions, 5 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.