gn: Tweak precompiled_header docs.

tools/gn/variables.cc

Index: tools/gn/variables.cc
diff --git a/tools/gn/variables.cc b/tools/gn/variables.cc
index 3b60c903557eb603c1f035f63c0d34ce87f28e66..66460e98341587eacea8303f39fb06ac1608efcc 100644
--- a/tools/gn/variables.cc
+++ b/tools/gn/variables.cc
@@ -1451,18 +1451,31 @@ const char kPrecompiledHeader_Help[] =
   config applying to this target specifies this value. In addition, the tool
   corresponding to the source files must also specify precompiled headers (see
   "gn help tool"). The tool will also specify what type of precompiled headers
-  to use.
+  to use, by setting precompiled_header_type to either "gcc" or "msvc".
 
   The precompiled header/source variables can be specified on a target or a
   config, but must be the same for all configs applying to a given target since
   a target can only have one precompiled header.
 
+  If you use both C and C++ sources, the precompiled header and source file
+  will be compiled once per language. You will want to make sure to wrap C++
+  includes in __cplusplus #ifdefs so the file will compile in C mode.
+
+GCC precompiled headers
+
+  When using GCC-style precompiled headers, "precompiled_source" contains the
+  path of a .h file that is precompiled and then included by all source files
+  in targets that set "precompiled_source".
+
+  The value of "precompiled_header" is not used with GCC-style precompiled
+  headers.

[Nico, 2017/03/03 20:24:34]

Fairly inconsistent with how MSVC-stype PCH works in GN, but that's today's
behavior from what I can tell. Chromium's .gn files do set precompiled_header
for GCC-style PCHs, but from what I can tell it has no effect. (Maybe GN should
warn if precompiled_header is set for gcc-style PCHs?)

+
 MSVC precompiled headers
 
   When using MSVC-style precompiled headers, the "precompiled_header" value is
   a string corresponding to the header. This is NOT a path to a file that GN
-  recognises, but rather the exact string that appears in quotes after an
-  #include line in source code. The compiler will match this string against
+  recognises, but rather the exact string that appears in quotes after
+  an #include line in source code. The compiler will match this string against

[Nico, 2017/03/03 20:24:34]

The motivation behind this CL was that the #include at the start of the line got
formatted as a comment in `gn help` output.

   includes or forced includes (/FI).
 
   MSVC also requires a source file to compile the header with. This must be
@@ -1470,10 +1483,6 @@ MSVC precompiled headers
   this IS a GN-style file name, and tells GN which source file to compile to
   make the .pch file used for subsequent compiles.
 
-  If you use both C and C++ sources, the precompiled header and source file
-  will be compiled using both tools. You will want to make sure to wrap C++
-  includes in __cplusplus #ifdefs so the file will compile in C mode.
-
   For example, if the toolchain specifies MSVC headers:
 
     toolchain("vc_x64") {
@@ -1500,6 +1509,15 @@ MSVC precompiled headers
       ...
 )";
 
+const char kPrecompiledHeaderType[] = "precompiled_header_type";
+const char kPrecompiledHeaderType_HelpShort[] =
+    "precompiled_header_type: [string] \"gcc\" or \"msvc\".";
+const char kPrecompiledHeaderType_Help[] =
+    R"(precompiled_header_type: [string] "gcc" or "msvc".
+
+  See "gn help precompiled_header".
+)";
+
 const char kPrecompiledSource[] = "precompiled_source";
 const char kPrecompiledSource_HelpShort[] =
     "precompiled_source: [file name] Source file to precompile.";
@@ -1904,6 +1922,7 @@ const VariableInfoMap& GetTargetVariables() {
     INSERT_VARIABLE(OutputPrefixOverride)
     INSERT_VARIABLE(Outputs)
     INSERT_VARIABLE(PrecompiledHeader)
+    INSERT_VARIABLE(PrecompiledHeaderType)
     INSERT_VARIABLE(PrecompiledSource)
     INSERT_VARIABLE(ProductType)
     INSERT_VARIABLE(Public)