Update gn's depfile help text to include more guidance.

tools/gn/variables.cc

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #include "tools/gn/variables.h"
 
 namespace variables {
 
 // Built-in variables ----------------------------------------------------------
 
@@ skipping 1007 matching lines @@
 const char kDepfile_HelpShort[] =
     "depfile: [string] File name for input dependencies for actions.";
 const char kDepfile_Help[] =
     "depfile: [string] File name for input dependencies for actions.\n"
     "\n"
     "  If nonempty, this string specifies that the current action or\n"
     "  action_foreach target will generate the given \".d\" file containing\n"
     "  the dependencies of the input. Empty or unset means that the script\n"
     "  doesn't generate the files.\n"
     "\n"
+    "  A depfile should be used only when a target depends on files that are\n"
+    "  not already specified by a target's inputs and sources. Likewise,\n"
+    "  depfiles should specify only those dependencies not already included\n"
+    "  in sources or inputs.\n"
+    "\n"
     "  The .d file should go in the target output directory. If you have more\n"
     "  than one source file that the script is being run over, you can use\n"
     "  the output file expansions described in \"gn help action_foreach\" to\n"
     "  name the .d file according to the input."
     "\n"
-    "  The format is that of a Makefile, and all of the paths should be\n"
-    "  relative to the root build directory.\n"
+    "  The format is that of a Makefile and all paths must be relative to the\n"
+    "  root build directory. Only one output may be listed and it must match\n"
+    "  the first output of the action.\n"
+    "\n"
+    "  Although depfiles are created by an action, they should not be listed\n"
+    "  in the action's \"outputs\" unless another target will use the file as\n"
+    "  an input.\n"
     "\n"
     "Example\n"
     "\n"
     "  action_foreach(\"myscript_target\") {\n"
     "    script = \"myscript.py\"\n"
     "    sources = [ ... ]\n"
     "\n"
     "    # Locate the depfile in the output directory named like the\n"
     "    # inputs but with a \".d\" appended.\n"
     "    depfile = \"$relative_target_output_dir/{{source_name}}.d\"\n"
@@ skipping 841 matching lines @@
     INSERT_VARIABLE(Testonly)
     INSERT_VARIABLE(Visibility)
     INSERT_VARIABLE(WriteRuntimeDeps)
   }
   return info_map;
 }
 
 #undef INSERT_VARIABLE
 
 }  // namespace variables