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

tools/gn/variables.cc

Index: tools/gn/variables.cc
diff --git a/tools/gn/variables.cc b/tools/gn/variables.cc
index f374934a5823851a36305081ae84020f5aae93df..644c8355edbd7a61da96d61c81c1a343c2755961 100644
--- a/tools/gn/variables.cc
+++ b/tools/gn/variables.cc
@@ -1025,13 +1025,23 @@ const char kDepfile_Help[] =
     "  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"

[Dirk Pranke, 2016/09/16 17:08:07]

Does anything actually use depfiles as inputs? 

I wonder if listing depfiles as outputs actually works correctly at all; doesn't
ninja treat them as transient files and delete them once they've been parsed and
stored in .ninja_deps? Maybe it doesn't delete them if they are also outputs?

[brettw, 2016/09/16 17:20:37]

Can you check on the Ninja list to see if this is good guidance?

[agrieve, 2016/09/16 17:51:42]

Good idea. Started thread:
https://groups.google.com/d/msg/ninja-build/buVgKjyVYU4/xFygHWaPBAAJ

[agrieve, 2016/09/19 18:14:18]

I've gotten no objections to the added advice.

     "\n"
     "Example\n"
     "\n"