From ea4f7cf35a4484a5a7e3eb8be9ccf3f7ffa05cf4 Mon Sep 17 00:00:00 2001
From: Jules Villard <jul@fb.com>
Date: Fri, 9 Oct 2020 07:56:46 -0700
Subject: [PATCH] [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 |  8 ++++++++
 infer/man/man1/infer-full.txt    | 12 +++++++++---
 infer/man/man1/infer.txt         |  9 +++++++++
 infer/src/base/Config.ml         |  8 +++++++-
 4 files changed, 33 insertions(+), 4 deletions(-)

diff --git a/infer/man/man1/infer-analyze.txt b/infer/man/man1/infer-analyze.txt
index 256e5f983..3c067c510 100644
--- a/infer/man/man1/infer-analyze.txt
+++ b/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:
diff --git a/infer/man/man1/infer-full.txt b/infer/man/man1/infer-full.txt
index 0757dac31..7d0696a6d 100644
--- a/infer/man/man1/infer-full.txt
+++ b/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)
diff --git a/infer/man/man1/infer.txt b/infer/man/man1/infer.txt
index b435bae4b..d2cbd137f 100644
--- a/infer/man/man1/infer.txt
+++ b/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).
 
diff --git a/infer/src/base/Config.ml b/infer/src/base/Config.ml
index 1764f8f79..02027de01 100644
--- a/infer/src/base/Config.ml
+++ b/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 =