Help: Clarify add_custom_command DEPENDS conversion to file paths

In commit f5126badd8 (add_custom_command: convert DEPENDS path arguments
to absolute paths, 2019-12-18, v3.17.0-rc1~263^2) we updated the
documentation to describe the behavior introduced by that commit.
However, the behavior was removed again by commit fd0ba705ce
(add_custom_command: check if a relative path should be an in-source
path, 2020-01-09, v3.17.0-rc1~141^2~4) without updating the
documentation.

Update the documentation again to describe the behavior as of the latter
commit.  Spell out the steps that `cmLocalGenerator::GetRealDependency`
and `cmTargetTraceDependencies::IsUtility` use to add file-level and
target-level dependencies.

1 files changed, 30 insertions, 14 deletions

diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst
index 576ed5b..69d6e9a 100644
--- a/Help/command/add_custom_command.rst
+++ b/Help/command/add_custom_command.rst
@@ -112,26 +112,42 @@ The options are:
   build time.
 
 ``DEPENDS``
-  Specify files on which the command depends.  Entries in the ``DEPENDS``
-  argument list which may also be target names are assumed to be target names,
-  so only entries which contain a path separator are detected as file paths.
+  Specify files on which the command depends.  Each argument is converted
+  to a dependency as follows:
+
+  1. If the argument is the name of a target (created by the
+     :command:`add_custom_target`, :command:`add_executable`, or
+     :command:`add_library` command) a target-level dependency is
+     created to make sure the target is built before any target
+     using this custom command.  Additionally, if the target is an
+     executable or library, a file-level dependency is created to
+     cause the custom command to re-run whenever the target is
+     recompiled.
+
+  2. If the argument is an absolute path, a file-level dependency
+     is created on that path.
+
+  3. If the argument is the name of a source file that has been
+     added to a target or on which a source file property has been set,
+     a file-level dependency is created on that source file.
+
+  4. If the argument is a relative path and it exists in the current
+     source directory, a file-level dependency is created on that
+     file in the current source directory.
+
+  5. Otherwise, a file-level dependency is created on that path relative
+     to the current binary directory.
+
   If any dependency is an ``OUTPUT`` of another custom command in the same
-  directory (``CMakeLists.txt`` file) CMake automatically brings the other
+  directory (``CMakeLists.txt`` file), CMake automatically brings the other
   custom command into the target in which this command is built.
   A target-level dependency is added if any dependency is listed as
   ``BYPRODUCTS`` of a target or any of its build events in the same
   directory to ensure the byproducts will be available.
-  If ``DEPENDS`` is not specified the command will run whenever
+
+  If ``DEPENDS`` is not specified, the command will run whenever
   the ``OUTPUT`` is missing; if the command does not actually
-  create the ``OUTPUT`` then the rule will always run.
-  If ``DEPENDS`` specifies any target (created by the
-  :command:`add_custom_target`, :command:`add_executable`, or
-  :command:`add_library` command) a target-level dependency is
-  created to make sure the target is built before any target
-  using this custom command.  Additionally, if the target is an
-  executable or library a file-level dependency is created to
-  cause the custom command to re-run whenever the target is
-  recompiled.
+  create the ``OUTPUT``, the rule will always run.
 
   Arguments to ``DEPENDS`` may use
   :manual:`generator expressions <cmake-generator-expressions(7)>`.