[scheduler] document option

Summary:
I wanted to change the default to "callgraph" but that created issues in
our tests, introducing flaky behaviours and even a failure due to trying
to run the pre-analysis multiple times (not 100% sure it was related).

Instead, document the various options and put the option in the analysis
manual so users can choose.

Reviewed By: martintrojer

Differential Revision: D24193751

fbshipit-source-id: 4b7c33a79

infer/man/man1/infer-analyze.txt

@@ -317,6 +317,14 @@ OPTIONS
        --results-dir,-o dir
            Write results and internal files in the specified directory
 
+       --scheduler { file | restart | callgraph }
+           Specify the scheduler used for the analysis phase:           - file: schedule one job per file
+           - callgraph: schedule one job per procedure, following the
+           syntactic call graph. Usually faster than "file".
+           - restart: same as callgraph but uses locking to try and avoid
+           duplicate work between different analysis processes and thus
+           performs better in some circumstances
+
        --no-self-in-block
            Deactivates: checker self-in-block: An Objective-C-specific
            analysis to detect when a block captures `self`. (Conversely:

infer/man/man1/infer-full.txt

@@ -1030,6 +1030,15 @@ OPTIONS
     See also infer-analyze(1), infer-capture(1), infer-explore(1),
            infer-report(1), and infer-run(1).
 
+       --scheduler { file | restart | callgraph }
+           Specify the scheduler used for the analysis phase:           - file: schedule one job per file
+           - callgraph: schedule one job per procedure, following the
+           syntactic call graph. Usually faster than "file".
+           - restart: same as callgraph but uses locking to try and avoid
+           duplicate work between different analysis processes and thus
+           performs better in some circumstances
+           See also infer-analyze(1).
+
        --select N
            Select bug number N. If omitted, prompt for input.           See also infer-explore(1).
 
@@ -1784,9 +1793,6 @@ INTERNAL OPTIONS
            "resource leak" write-your-own-checker exercise. (Conversely:
            --no-resource-leak-lab)
 
-       --scheduler { file | restart | callgraph }
-           Specify the scheduler used for the analysis phase
-
        --scuba-logging
            Activates: (direct) logging to scuba (Conversely:
            --no-scuba-logging)

infer/man/man1/infer.txt

@@ -1030,6 +1030,15 @@ OPTIONS
     See also infer-analyze(1), infer-capture(1), infer-explore(1),
            infer-report(1), and infer-run(1).
 
+       --scheduler { file | restart | callgraph }
+           Specify the scheduler used for the analysis phase:           - file: schedule one job per file
+           - callgraph: schedule one job per procedure, following the
+           syntactic call graph. Usually faster than "file".
+           - restart: same as callgraph but uses locking to try and avoid
+           duplicate work between different analysis processes and thus
+           performs better in some circumstances
+           See also infer-analyze(1).
+
        --select N
            Select bug number N. If omitted, prompt for input.           See also infer-explore(1).
 

infer/src/base/Config.ml

@@ -2252,8 +2252,14 @@ and export_changed_functions =
 
 and scheduler =
   CLOpt.mk_symbol ~long:"scheduler" ~default:File ~eq:equal_scheduler
+    ~in_help:InferCommand.[(Analyze, manual_generic)]
     ~symbols:[("file", File); ("restart", Restart); ("callgraph", SyntacticCallGraph)]
-    "Specify the scheduler used for the analysis phase"
+    "Specify the scheduler used for the analysis phase:\n\
+     - file: schedule one job per file\n\
+     - callgraph: schedule one job per procedure, following the syntactic call graph. Usually \
+     faster than \"file\".\n\
+     - restart: same as callgraph but uses locking to try and avoid duplicate work between \
+     different analysis processes and thus performs better in some circumstances"
 
 
 and test_filtering =