Enhance GN documentation.

tools/gn/variables.cc

Index: tools/gn/variables.cc
diff --git a/tools/gn/variables.cc b/tools/gn/variables.cc
index 0b7ac7a1e5bef7c8f411441c7c1cd5d45e0efa72..6f9c8486fe323f3a87a143519e1647dd371b9ab9 100644
--- a/tools/gn/variables.cc
+++ b/tools/gn/variables.cc
@@ -165,7 +165,7 @@ const char kCurrentToolchain_Help[] =
     "  use this to make toolchain-related decisions in the build. See also\n"
     "  \"default_toolchain\".\n"
     "\n"
-    "Example:\n"
+    "Example\n"
     "\n"
     "  if (current_toolchain == \"//build:64_bit_toolchain\") {\n"
     "    executable(\"output_thats_64_bit_only\") {\n"
@@ -242,7 +242,7 @@ const char kRootOutDir_Help[] =
     "  See also \"target_out_dir\" which is usually a better location for\n"
     "  output files. It will be inside the root output dir.\n"
     "\n"
-    "Example:\n"
+    "Example\n"
     "\n"
     "  action(\"myscript\") {\n"
     "    # Pass the output dir to the script.\n"
@@ -268,7 +268,7 @@ const char kTargetGenDir_Help[] =
     "\n"
     "  See also \"gn help root_gen_dir\".\n"
     "\n"
-    "Example:\n"
+    "Example\n"
     "\n"
     "  action(\"myscript\") {\n"
     "    # Pass the generated output dir to the script.\n"
@@ -294,7 +294,7 @@ const char kTargetOutDir_Help[] =
     "\n"
     "  See also \"gn help root_out_dir\".\n"
     "\n"
-    "Example:\n"
+    "Example\n"
     "\n"
     "  action(\"myscript\") {\n"
     "    # Pass the output dir to the script.\n"
@@ -658,7 +658,8 @@ const char kDataDeps_Help[] =
     "\n"
     "  See also \"gn help deps\" and \"gn help data\".\n"
     "\n"
-    "Example:\n"
+    "Example\n"
+    "\n"
     "  executable(\"foo\") {\n"
     "    deps = [ \"//base\" ]\n"
     "    data_deps = [ \"//plugins:my_runtime_plugin\" ]\n"
@@ -676,7 +677,8 @@ const char kDefines_Help[] =
     "  strings may or may not include an \"=\" to assign a value.\n"
     COMMON_ORDERING_HELP
     "\n"
-    "Example:\n"
+    "Example\n"
+    "\n"
     "  defines = [ \"AWESOME_FEATURE\", \"LOG_LEVEL=3\" ]\n";
 
 const char kDepfile[] = "depfile";
@@ -698,7 +700,8 @@ const char kDepfile_Help[] =
     "  The format is that of a Makefile, and all of the paths should be\n"
     "  relative to the root build directory.\n"
     "\n"
-    "Example:\n"
+    "Example\n"
+    "\n"
     "  action_foreach(\"myscript_target\") {\n"
     "    script = \"myscript.py\"\n"
     "    sources = [ ... ]\n"
@@ -788,7 +791,8 @@ const char kIncludeDirs_Help[] =
     "  the files in the affected target.\n"
     COMMON_ORDERING_HELP
     "\n"
-    "Example:\n"
+    "Example\n"
+    "\n"
     "  include_dirs = [ \"src/include\", \"//third_party/foo\" ]\n";
 
 const char kInputs[] = "inputs";
@@ -810,10 +814,10 @@ const char kInputs_Help[] =
     "  uses via imports (the main script itself will be an implcit dependency\n"
     "  of the action so need not be listed).\n"
     "\n"
-    "  For action targets, inputs should be the entire set of inputs the\n"
-    "  script needs. For action_foreach targets, inputs should be the set of\n"
-    "  dependencies that don't change. These will be applied to each script\n"
-    "  invocation over the sources.\n"
+    "  For action targets, inputs and sources are treated the same, but from\n"
+    "  a style perspective, it's recommended to follow the same rule as\n"
+    "  action_foreach and put helper files in the inputs, and the data used\n"
+    "  by the script (if any) in sources.\n"
     "\n"
     "  Note that another way to declare input dependencies from an action\n"
     "  is to have the action write a depfile (see \"gn help depfile\"). This\n"
@@ -822,6 +826,23 @@ const char kInputs_Help[] =
     "  efficient than doing processing while running GN to determine the\n"
     "  inputs, and is easier to keep in-sync than hardcoding the list.\n"
     "\n"
+    "Script input gotchas\n"
+    "\n"
+    "  It may be tempting to write a script that enumerates all files in a\n"
+    "  directory as inputs. Don't do this! Even if you specify all the files\n"
+    "  in the inputs or sources in the GN target (or worse, enumerate the\n"
+    "  files in an exec_script call when running GN, which will be slow), the\n"
+    "  dependencies will be broken.\n"
+    "\n"
+    "  The problem happens if a file is ever removed because the inputs are\n"
+    "  not listed on the command line to the script. Because the script\n"
+    "  hasn't changed and all inputs are up-to-date, the script will not\n"
+    "  re-run and you will get a stale build. Instead, either list all\n"
+    "  inputs on the command line to the script, or if there are many, create\n"
+    "  a separate list file that the script reads. As long as this file is\n"
+    "  listed in the inputs, the build will detect when it has changed in any\n"
+    "  way and the action will re-run.\n"
+    "\n"
     "Inputs for binary targets\n"
     "\n"
     "  Any input dependencies will be resolved before compiling any sources.\n"
@@ -829,6 +850,14 @@ const char kInputs_Help[] =
     "  files in a target are compiled. So if you depend on generated headers,\n"
     "  you do not typically need to list them in the inputs section.\n"
     "\n"
+    "  Inputs for binary targets will be treated as order-only dependencies,\n"
+    "  meaning that they will be forced up-to-date before compiling or\n"
+    "  any files in the target, but changes in the inputs will not\n"
+    "  necessarily force the target to compile. This is because it is\n"
+    "  expected that the compiler will report the precise list of input\n"
+    "  dependencies required to recompile each file once the initial build\n"
+    "  is done.\n"
+    "\n"
     "Example\n"
     "\n"
     "  action(\"myscript\") {\n"
@@ -876,7 +905,8 @@ const char kLibDirs_Help[] =
     COMMON_LIB_INHERITANCE_HELP
     COMMON_ORDERING_HELP
     "\n"
-    "Example:\n"
+    "Example\n"
+    "\n"
     "  lib_dirs = [ \"/usr/lib/foo\", \"lib/doom_melon\" ]\n";
 
 const char kLibs[] = "libs";
@@ -904,7 +934,8 @@ const char kLibs_Help[] =
     COMMON_LIB_INHERITANCE_HELP
     COMMON_ORDERING_HELP
     "\n"
-    "Examples:\n"
+    "Examples\n"
+    "\n"
     "  On Windows:\n"
     "    libs = [ \"ctl3d.lib\" ]\n"
     "  On Linux:\n"
@@ -919,7 +950,32 @@ const char kOutputExtension_Help[] =
     "  Normally the file extension for a target is based on the target\n"
     "  type and the operating system, but in rare cases you will need to\n"
     "  override the name (for example to use \"libfreetype.so.6\" instead\n"
-    "  of libfreetype.so on Linux).";
+    "  of libfreetype.so on Linux).\n"
+    "\n"
+    "  This value should not include a leading dot. If undefined or empty,\n"
+    "  the default_output_extension specified on the tool will be used.\n"
+    "  The output_extension will be used in the \"{{output_extension}}\"\n"
+    "  expansion which the linker tool will generally use to specify the\n"
+    "  output file name. See \"gn help tool\".\n"
+    "\n"
+    "Example\n"
+    "\n"
+    "  shared_library(\"freetype\") {\n"
+    "    if (is_linux) {\n"
+    "      # Call the output \"libfreetype.so.6\"\n"
+    "      output_extension = \"so.6\"\n"
+    "    }\n"
+    "    ...\n"
+    "  }\n"
+    "\n"
+    "  # On Windows, generate a \"mysettings.cpl\" control panel applet.\n"
+    "  # Control panel applets are actually special shared libraries.\n"
+    "  if (is_win) {\n"
+    "    shared_library(\"mysettings\") {\n"
+    "      output_extension = \"cpl\"\n"
+    "      ...\n"
+    "    }\n"
+    "  }\n";
 
 const char kOutputName[] = "output_name";
 const char kOutputName_HelpShort[] =
@@ -936,11 +992,15 @@ const char kOutputName_Help[] =
     "\n"
     "  The output name should have no extension or prefixes, these will be\n"
     "  added using the default system rules. For example, on Linux an output\n"
-    "  name of \"foo\" will produce a shared library \"libfoo.so\".\n"
+    "  name of \"foo\" will produce a shared library \"libfoo.so\". There\n"
+    "  is no way to override the output prefix of a linker tool on a per-\n"
+    "  target basis. If you need more flexibility, create a copy target\n"
+    "  to produce the file you want.\n"
     "\n"
     "  This variable is valid for all binary output target types.\n"
     "\n"
-    "Example:\n"
+    "Example\n"
+    "\n"
     "  static_library(\"doom_melon\") {\n"
     "    output_name = \"fluffy_bunny\"\n"
     "  }\n";
@@ -952,13 +1012,26 @@ const char kOutputs_Help[] =
     "outputs: Output files for actions and copy targets.\n"
     "\n"
     "  Outputs is valid for \"copy\", \"action\", and \"action_foreach\"\n"
-    "  target types and indicates the resulting files. The values may contain\n"
-    "  source expansions to generate the output names from the sources (see\n"
-    "  \"gn help source_expansion\").\n"
-    "\n"
-    "  For copy targets, the outputs is the destination for the copied\n"
-    "  file(s). For actions, the outputs should be the list of files\n"
-    "  generated by the script.\n";
+    "  target types and indicates the resulting files. Outputs must always\n"
+    "  refer to files in the build directory.\n"
+    "\n"
+    "  copy\n"
+    "    Copy targets should have exactly one entry in the outputs list. If\n"
+    "    there is exactly one source, this can be a literal file name or a\n"
+    "    source expansion. If there is more than one source, this must\n"
+    "    contain a source expansion to map a single input name to a single\n"
+    "    output name. See \"gn help copy\".\n"
+    "\n"
+    "  action_foreach\n"
+    "    Action_foreach targets must always use source expansions to map\n"
+    "    input files to output files. There can be more than one output,\n"
+    "    which means that each invocation of the script will produce a set of\n"
+    "    files (presumably based on the name of the input file). See\n"
+    "    \"gn help action_foreach\".\n"
+    "\n"
+    "  action\n"
+    "    Action targets (excluding action_foreach) must list literal output\n"
+    "    file(s) with no source expansions. See \"gn help action\".\n";
 
 const char kPrecompiledHeader[] = "precompiled_header";
 const char kPrecompiledHeader_HelpShort[] =
@@ -1058,7 +1131,8 @@ const char kPublic_Help[] =
     "  sections of targets. If a file is included that is not known to the\n"
     "  build, it will be allowed.\n"
     "\n"
-    "Examples:\n"
+    "Examples\n"
+    "\n"
     "  These exact files are public:\n"
     "    public = [ \"foo.h\", \"bar.h\" ]\n"
     "\n"
@@ -1154,7 +1228,37 @@ const char kSources_HelpShort[] =
 const char kSources_Help[] =
     "sources: Source files for a target\n"
     "\n"
-    "  A list of files relative to the current buildfile.\n";
+    "  A list of files. Non-absolute paths will be resolved relative to the\n"
+    "  current build file.\n"
+    "\n"
+    "Sources for binary targets\n"
+    "\n"
+    "  For binary targets (source sets, executables, and libraries), the\n"
+    "  known file types will be compiled with the associated tools. Unknown\n"
+    "  file types and headers will be skipped. However, you should still\n"
+    "  list all C/C+ header files so GN knows about the existance of those\n"
+    "  files for the purposes of include checking.\n"
+    "\n"
+    "  As a special case, a file ending in \".def\" will be treated as a\n"
+    "  Windows module definition file. It will be appended to the link\n"
+    "  line with a preceeding \"/DEF:\" string. There must be at most one\n"
+    "  .def file in a target and they do not cross dependency boundaries\n"
+    "  (so specifying a .def file in a static library or source set will have\n"
+    "  no effect on the executable or shared library they're linked into).\n"
+    "\n"
+    "Sources for non-binary targets\n"
+    "\n"
+    "  action_foreach\n"
+    "    The sources are the set of files that the script will be executed\n"
+    "    over. The script will run once per file.\n"
+    "\n"
+    "  action\n"
+    "    The sources will be treated the same as inputs. See "
+         "\"gn help inputs\"\n"
+    "    for more information and usage advice.\n"
+    "\n"
+    "  copy\n"
+    "    The source are the source files to copy.\n";
 
 const char kTestonly[] = "testonly";
 const char kTestonly_HelpShort[] =