Clarify how the `analyze` step should work in MB (and elsewhere).

tools/mb/docs/user_guide.md

 # The MB (Meta-Build wrapper) user guide
 
 [TOC]
 
 ## Introduction
 
 `mb` is a simple python wrapper around the GYP and GN meta-build tools to
 be used as part of the GYP->GN migration.
 
 It is intended to be used by bots to make it easier to manage the configuration
@@ skipping 16 matching lines @@
 mb analyze -c chromium_linux_rel //out/Release input.json output.json
 ```
 
 Either the `-c/--config` flag or the `-m/--master` and `-b/--builder` flags
 must be specified so that `mb` can figure out which config to use.
 
 The first positional argument must be a GN-style "source-absolute" path
 to the build directory.
 
 The second positional argument is a (normal) path to a JSON file containing
-a single object with two fields:
+a single object with the following fields:
 
-  * `files`: an array of the modified filenames to check (as
-    paths relative to the checkout root).
-  * `targets`: an array of the unqualified target names to check.
+  * `files`: an array of the modified filenames to check (as paths relative to
+    the checkout root).
+  * `compile_targets`: an array of (ninja) build targets that reflect the stuff
+    we might want to rebuild if affected by the patch. The targets may contain
+    *meta* (GN: group, GYP: none) targets like 'blink_tests' or
+    'chromium_builder_tests', or even the ninja-specific 'all' target. Any
+    empty list will be treated as equivalent to ["all"] (build everything).
+  * `test_targets`: an array of (ninja) build targets that, if affected, will
+    affect which tests we want to run. This is usually a *subset* of
+    `compile_targets`. An empty list is treated as if there are no tests
+    to run.
+  * `targets`: a legacy field that resembled a union of `compile_targets`
+    and `test_targets`. Support for this field will be removed once the
+    bots have been updated to use compile_targets and test_targets instead.
 
 The third positional argument is a (normal) path to where mb will write
 the result, also as a JSON object. This object may contain the following
 fields:
 
   * `error`: this should only be present if something failed.
-  * `targets`: the subset of the input `targets` that depend on the
-    input `files`.
-  * `build_targets`: the minimal subset of targets needed to build all
-    of `targets` that were affected.
-  * `status`: one of three strings:
+  * `compile_targets`: the list of ninja targets that should be passed
+    directly to the corresponding ninja / compile.py invocation. This
+    list may contain entries that are *not* listed in the input (see
+    [design_spec.md](the design spec) for how this works).
+  * `test_targets`: the subset of the input `test_targets` that are
+    potentially out of date, indicating that the matching test steps
+    should be re-run.
+  * `targets`: a legacy field that indicates the subset of the input `targets`
+    that depend on the input `files`.
+  * `build_targets`: a legacy field that indicates the minimal subset of
+    targets needed to build all of `targets` that were affected.
+  * `status`: a legacy field containing one of three strings:
+
     * `"Found dependency"` (build the `build_targets`)
     * `"No dependency"` (i.e., no build needed)
     * `"Found dependency (all)"` (build everything, in which case
-      `targets` and `build_targets` are not returned).
+       `targets` and `build_targets` are not returned).
+
+    This field is no longer needed with the newer compile_targets and
+    test_targets outputs, and will be removed along with `targets` and
+    `build_targets` once all the bots have been updated.

[Dirk Pranke, 2015/11/06 04:34:19]

NB: this might surprise you. 

[Dirk Pranke, 2015/11/06 05:08:47]

Actually, having thought about this some more, I think this change is wrong and
we should
keep 'status' to distinguish between the 'no compile necessary' case and the
'compile
necessary, build everything by passing no targets to ninja' case (the Nico
clause).

+
+The differences between `compile_targets` and `test_targets` and between
+how they are treated as input and output is subtle and complicated; see
+[design_spec.md](the design spec) for details. We won't even go into how
+the `targets` and `build_targets` differ from each other or from
+`compile_targets` and `test_targets`.
 
 The `-b/--builder`, `-c/--config`, `-f/--config-file`, `-m/--master`,
 `-q/--quiet`, and `-v/--verbose` flags work as documented for `mb gen`.
 
-
 ### `mb gen`
 
 `mb gen` is responsible for generating the Ninja files by invoking either GYP
 or GN as appropriate. It takes arguments to specify a build config and
 a directory, then runs GYP or GN as appropriate:
 
 ```
 % mb gen -m tryserver.chromium.linux -b linux_rel //out/Release
 % mb gen -c linux_rel_trybot //out/Release
 ```
@@ skipping 164 matching lines @@
 run than you expect; running `'mb -v'` will print what it's doing and
 run the commands; `'mb -n'` will print what it will do but *not* run
 the commands.
 
 If you hit weirder things than that, add some print statements to the
 python script, send a question to gn-dev@chromium.org, or
 [file a bug](https://crbug.com/new) with the label
 'mb' and cc: dpranke@chromium.org.