Add not_needed function

tools/gn/docs/reference.md

 # GN Reference
 
 *This page is automatically generated from* `gn help --markdown all`.
 
 ## Contents
 
 *   [Commands](#commands)
     *   [analyze: Analyze which targets are affected by a list of files.](#analyze)
     *   [args: Display or configure arguments declared by the build.](#args)
     *   [check: Check header dependencies.](#check)
@@ skipping 24 matching lines @@
     *   [declare_args: Declare build arguments.](#declare_args)
     *   [defined: Returns whether an identifier is defined.](#defined)
     *   [exec_script: Synchronously run a script and return the output.](#exec_script)
     *   [foreach: Iterate over a list.](#foreach)
     *   [forward_variables_from: Copies variables from a different scope.](#forward_variables_from)
     *   [get_label_info: Get an attribute from a target's label.](#get_label_info)
     *   [get_path_info: Extract parts of a file or directory name.](#get_path_info)
     *   [get_target_outputs: [file list] Get the list of outputs from a target.](#get_target_outputs)
     *   [getenv: Get an environment variable.](#getenv)
     *   [import: Import a file into the current scope.](#import)
+    *   [not_needed: Mark variables from scope as unusedd.](#not_needed)
     *   [pool: Defines a pool object.](#pool)
     *   [print: Prints to the console.](#print)
     *   [process_file_template: Do template expansion over a list of files.](#process_file_template)
     *   [read_file: Read a file into a variable.](#read_file)
     *   [rebase_path: Rebase a file or directory to another location.](#rebase_path)
     *   [set_default_toolchain: Sets the default toolchain name.](#set_default_toolchain)
     *   [set_defaults: Set default values for a target type.](#set_defaults)
     *   [set_sources_assignment_filter: Set a pattern to filter source files.](#set_sources_assignment_filter)
     *   [split_list: Splits a list into N different sub-lists.](#split_list)
     *   [template: Define a template rule.](#template)
@@ skipping 536 matching lines @@
 #### **Examples**
 ```
   gn format //some/BUILD.gn
   gn format some\\BUILD.gn
   gn format /abspath/some/BUILD.gn
   gn format --stdin
 ```
 ### <a name="gen:"></a>**gn gen**: Generate ninja files.
 
 ```
-  gn gen [<ide options>] <out_dir>
+  gn gen [--check] [<ide options>] <out_dir>
 
   Generates ninja files from the current tree and puts them in the given output
   directory.
 
   The output directory can be a source-repo-absolute path name such as:
       //out/foo
   Or it can be a directory relative to the current directory such as:
       out/foo
 
+  "gn gen --check" is the same as running "gn check". See "gn help check"
+  for documentation on that mode.
+
   See "gn help switches" for the common command-line switches.
 ```
 
 #### **IDE options**
 
 ```
   GN optionally generates files for IDE. Possibilities for <ide options>
 
   --ide=<ide_name>
       Generate files for an IDE. Currently supported values:
@@ skipping 60 matching lines @@
   a list of include paths and defines. Because GN does not generate a full
   .cproject definition, it is not possible to properly define includes/defines
   for each file individually. Instead, one set of includes/defines is generated
   for the entire project. This works fairly well but may still result in a few
   indexer issues here and there.
 ```
 
 #### **Generic JSON Output**
 
 ```
-  Dumps target information to JSON file and optionally invokes python script on
-  generated file. See comments at the beginning of json_project_writer.cc and
-  desc_builder.cc for overview of JSON file format.
+  Dumps target information to a JSON file and optionally invokes a
+  python script on the generated file. See the comments at the beginning
+  of json_project_writer.cc and desc_builder.cc for an overview of the JSON
+  file format.
 
   --json-file-name=<json_file_name>
       Overrides default file name (project.json) of generated JSON file.
 
   --json-ide-script=<path_to_python_script>
       Executes python script after the JSON file is generated. Path can be
       project absolute (//), system absolute (/) or relative, in which case the
       output directory will be base. Path to generated JSON file will be first
       argument when invoking script.
 
@@ skipping 1416 matching lines @@
 ```
 
 #### **Examples**
 
 ```
   import("//build/rules/idl_compilation_rule.gni")
 
   # Looks in the current directory.
   import("my_vars.gni")
 ```
+### <a name="not_needed"></a>**not_needed**: Mark variables from scope as unused.
+
+```
+  not_needed(from_scope, variable_list_or_star,
+             variable_to_ignore_list = [])
+
+  Mark the variables from the given scope as not being used in the current
+  scope. Any past or future uses of these variables within the current scope
+  will fail with an error.
+```
+
+#### **Example**
+
+```
+  not_needed(invoker, "*", [ "config" ])
+  not_needed(invoker, [ "data_deps", "deps" ])
+```
 ### <a name="pool"></a>**pool**: Defines a pool object.
 
 ```
   Pool objects can be applied to a tool to limit the parallelism of the
   build. This object has a single property "depth" corresponding to
   the number of tasks that may run simultaneously.
 
   As the file containing the pool definition may be executed in the
   context of more than one toolchain it is recommended to specify an
   explicit toolchain when defining and referencing a pool.
@@ skipping 4007 matching lines @@
     *   [--root: Explicitly specify source root.](#--root)
     *   [--runtime-deps-list-file: Save runtime dependencies for targets in file.](#--runtime-deps-list-file)
     *   [--script-executable: Set the executable used to execute scripts.](#--script-executable)
     *   [--threads: Specify number of worker threads.](#--threads)
     *   [--time: Outputs a summary of how long everything took.](#--time)
     *   [--tracelog: Writes a Chrome-compatible trace log to the given file.](#--tracelog)
     *   [-v: Verbose logging.](#-v)
     *   [--version: Prints the GN version number and exits.](#--version)
 ```