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

tools/mb/docs/user_guide.md

Index: tools/mb/docs/user_guide.md
diff --git a/tools/mb/docs/user_guide.md b/tools/mb/docs/user_guide.md
index 7f002919aeae663b30d4339d48f79957a0c793bb..f31897f7a4caf2b75de85dc37b1eea5d7d951575 100644
--- a/tools/mb/docs/user_guide.md
+++ b/tools/mb/docs/user_guide.md
@@ -34,31 +34,59 @@ 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:
-
-  * `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.
+a single object with the following fields:
+
+  * `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