Update reference, add script to do so.

Updates reference.md with the latest GN changes.

Adds a simple script to generate this so you don't have to remember or
look up the correct switches.

Change-Id: If641978f445014b93be3d9a10f59b5415de4faf4
Reviewed-on: https://gn-review.googlesource.com/c/gn/+/14561
Commit-Queue: Brett Wilson <brettw@chromium.org>
Reviewed-by: Takuto Ikuta <tikuta@google.com>
diff --git a/docs/reference.md b/docs/reference.md
index 3ebed7a..8dd8ba8 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -919,21 +919,37 @@
       replay of individual compilations independent of the build system.
       This is an unstable format and likely to change without warning.
+  --add-export-compile-commands=<label_pattern>
+      Adds an additional label pattern (see "gn help label_pattern") of a
+      target to add to the compilation database. This pattern is appended to any
+      list values specified in the export_compile_commands variable in the
+      .gn file (see "gn help dotfile"). This allows the user to add additional
+      targets to the compilation database that the project doesn't add by default.
+      To add more than one value, specify this switch more than once. Each
+      invocation adds an additional label pattern.
+      Example:
+        --add-export-compile-commands=//tools:my_tool
+        --add-export-compile-commands="//base/*"
-      Produces a compile_commands.json file in the root of the build directory
-      containing an array of “command objects”, where each command object
-      specifies one way a translation unit is compiled in the project. If a list
-      of target_name is supplied, only targets that are reachable from any
-      target in any build file whose name is target_name will be used for
-      “command objects” generation, otherwise all available targets will be used.
-      This is used for various Clang-based tooling, allowing for the replay of
-      individual compilations independent of the build system.
-      e.g. "foo" will match:
-      - "//path/to/src:foo"
-      - "//other/path:foo"
-      - "//foo:foo"
+      DEPRECATED https://bugs.chromium.org/p/gn/issues/detail?id=302.
+      Please use --add-export-compile-commands for per-user configuration, and
+      the "export_compile_commands" value in the project-level .gn file (see
+      "gn help dotfile") for per-project configuration.
+      Overrides the value of the export_compile_commands in the .gn file (see
+      "gn help dotfile") as well as the --add-export-compile-commands switch.
+      Unlike the .gn setting, this switch takes a legacy format which is a list
+      of target names that are matched in any directory. For example, "foo" will
+      match:
+       - "//path/to/src:foo"
+       - "//other/path:foo"
+       - "//foo:foo"
       and not match:
-      - "//foo:bar"
+       - "//foo:bar"
 ### <a name="cmd_help"></a>**gn help &lt;anything&gt;**
@@ -6953,6 +6969,28 @@
+  export_compile_commands [optional]
+      A list of label patterns for which to generate a Clang compilation
+      database (see "gn help label_pattern" for the string format).
+      When specified, GN will generate a compile_commands.json file in the root
+      of the build directory containing information on how to compile each
+      source file reachable from any label matching any pattern in the list.
+      This is used for Clang-based tooling and some editor integration. See
+      https://clang.llvm.org/docs/JSONCompilationDatabase.html
+      The switch --add-export-compile-commands to "gn gen" (see "gn help gen")
+      appends to this value which provides a per-user way to customize it.
+      The deprecated switch --export-compile-commands to "gn gen" (see "gn help
+      gen") adds to the export target list using a different format.
+      Example:
+        export_compile_commands = [
+          "//base/*",
+          "//tools:doom_melon",
+        ]
   root [optional]
       Label of the root build target. The GN build will start by loading the
       build file containing this target name. This defaults to "//:" which will
diff --git a/tools/update_reference.sh b/tools/update_reference.sh
new file mode 100755
index 0000000..50427e1
--- /dev/null
+++ b/tools/update_reference.sh
@@ -0,0 +1,12 @@
+# Check for the existance of the AUTHORS file as an easy way to determine if
+# it's being run from the correct directory.
+if test -f "AUTHORS"; then
+    echo Building gn...
+    ninja -C out gn
+    echo Generating new docs/reference.md...
+    out/gn help --markdown all > docs/reference.md
+    echo Please run this command from the GN checkout root directory.