ENH: Document scope of add_custom_command outputs

This explicitly states the scope of add_custom_command rules in
the documentation of add_custom_command and add_custom_target.
See issue #8815.

1 files changed, 8 insertions, 3 deletions

diff --git a/Source/cmAddCustomCommandCommand.h b/Source/cmAddCustomCommandCommand.h
index 7829b61..8add970 100644
--- a/Source/cmAddCustomCommandCommand.h
+++ b/Source/cmAddCustomCommandCommand.h
@@ -75,9 +75,10 @@ public:
       "                     [IMPLICIT_DEPENDS <lang1> depend1 ...]\n"
       "                     [WORKING_DIRECTORY dir]\n"
       "                     [COMMENT comment] [VERBATIM] [APPEND])\n"
-      "This defines a new command that can be executed during the build "
-      "process. The outputs named should be listed as source files in the "
-      "target for which they are to be generated. "
+      "This defines a command to generate specified OUTPUT file(s).  "
+      "A target created in the same directory (CMakeLists.txt file) that "
+      "specifies any output of the custom command as a source file is given "
+      "a rule to generate the file using the command at build time.  "
       "If an output name is a relative path it will be interpreted "
       "relative to the build tree directory corresponding to the current "
       "source directory. "
@@ -151,6 +152,10 @@ public:
       "this does NOT add a file-level dependency that would cause the "
       "custom command to re-run whenever the executable is recompiled.\n"
 
+      "The DEPENDS option specifies files on which the command depends.  "
+      "If any dependency is an OUTPUT of another custom command in the "
+      "same directory (CMakeLists.txt file) CMake automatically brings the "
+      "other custom command into the target in which this command is built.  "
       "If DEPENDS specifies any target (created by an ADD_* command) "
       "a target-level dependency is created to make sure the target is "
       "built before any target using this custom command.  Additionally, "