[help] update help sections

Summary:
This reorganises the contents of `infer --help`:

- Headings are more prominent (start with `**`)
- New "Java" section
- Delete "Analysis" section, distribute contents over other sections
- New "Quandary" section
- Under the hood, new "Buffer Overruns" and "Crashcontext" sections, but do not show them as we don't expect external use yet, although that may be a bit arbitrary
- typo: `--bufferoverrn` -> `--bufferoverrun`
- move some options from one section to another

Reviewed By: jberdine

Differential Revision: D4537500

fbshipit-source-id: a789375

infer/src/base/CommandLineOption.ml

@@ -55,10 +55,11 @@ let warnf =
   else if not is_originator then fun fmt -> F.ifprintf F.err_formatter fmt
   else F.eprintf
 
-type section = Analysis | Clang | Driver | Java | Print [@@deriving compare]
+type section = Analysis | BufferOverrun | Clang | Crashcontext | Driver | Java | Print | Quandary
+[@@deriving compare]
 
 let equal_section = [%compare.equal : section ]
-let all_sections = [ Analysis; Clang; Driver; Java; Print ]
+let all_sections = [ Analysis; BufferOverrun; Clang; Crashcontext; Driver; Java; Print; Quandary ]
 
 type 'a parse = Infer of 'a | Javac | NoParse [@@deriving compare]
 
@@ -77,7 +78,7 @@ let to_parse_tag = function | Infer _ -> Infer () | Javac -> Javac | NoParse ->
 
 let accept_unknown_args = function
   | Infer Print | Javac | NoParse -> true
-  | Infer Analysis | Infer Clang | Infer Driver | Infer Java -> false
+  | Infer (Analysis | BufferOverrun | Clang | Crashcontext | Driver | Java | Quandary) -> false
 
 type desc = {
   long: string; short: string; meta: string; doc: string; spec: spec;
@@ -605,7 +606,7 @@ let set_curr_speclist_for_parse_action ~incomplete ~usage parse_action =
   in
   let add_to_curr_speclist ?(add_help=false) ?header parse_action =
     let mk_header_spec heading =
-      ("", Unit (fun () -> ()), "\n  " ^ heading ^ "\n") in
+      ("", Unit (fun () -> ()), "\n## " ^ heading ^ "\n") in
     let exe_descs =
       match parse_action with
       | Infer section ->
@@ -638,8 +639,9 @@ let set_curr_speclist_for_parse_action ~incomplete ~usage parse_action =
   curr_speclist := [];
   if equal_parse_action parse_action (Infer Driver) then (
     add_to_curr_speclist ~add_help:true ~header:"Driver options" (Infer Driver);
-    add_to_curr_speclist ~header:"Analysis (backend) options" (Infer Analysis);
+    add_to_curr_speclist ~header:"Clang-specific options" (Infer Clang);
-    add_to_curr_speclist ~header:"Clang frontend options" (Infer Clang)
+    add_to_curr_speclist ~header:"Java-specific options" (Infer Java);
+    add_to_curr_speclist ~header:"Quandary checker options" (Infer Quandary)
   ) else
     add_to_curr_speclist ~add_help:true parse_action
   ;

infer/src/base/CommandLineOption.mli

@@ -12,7 +12,8 @@
 open! IStd
 
 (** a section is a part of infer that can be affected by an infer option *)
-type section = Analysis | Clang | Driver | Java | Print [@@deriving compare]
+type section = Analysis | BufferOverrun | Clang | Crashcontext | Driver | Java | Print | Quandary
+[@@deriving compare]
 
 val all_sections : section list
 

infer/src/base/Config.ml

@@ -527,12 +527,12 @@ and blacklist =
 
 and bootclasspath =
   CLOpt.mk_string_opt ~long:"bootclasspath"
-    ~parse_mode:CLOpt.(Infer [Driver])
+    ~parse_mode:CLOpt.(Infer [Java])
     "Specify the Java bootclasspath"
 
 and bo_debug =
   CLOpt.mk_int ~default:0 ~long:"bo-debug"
-    ~parse_mode:CLOpt.(Infer [Driver]) "Debug mode for buffer-overrun checker"
+    ~parse_mode:CLOpt.(Infer [BufferOverrun]) "Debug mode for buffer-overrun checker"
 
 (** Automatically set when running from within Buck *)
 and buck =
@@ -589,7 +589,7 @@ and changed_files_index =
 
 and check_duplicate_symbols =
   CLOpt.mk_bool ~long:"check-duplicate-symbols"
-    ~parse_mode:CLOpt.(Infer [Analysis])
+    ~parse_mode:CLOpt.(Infer [Clang])
     "Check if a symbol with the same name is defined in more than one file."
 
 and checkers, crashcontext, eradicate, quandary, threadsafety, bufferoverrun =
@@ -599,12 +599,12 @@ and checkers, crashcontext, eradicate, quandary, threadsafety, bufferoverrun =
   in
   let crashcontext =
     CLOpt.mk_bool_group ~deprecated:["crashcontext"] ~long:"crashcontext"
-      "Activate the crashcontext checker for java stack trace context reconstruction"
+      "Activate the crashcontext checker for Java stack trace context reconstruction"
       [checkers] []
   in
   let eradicate =
     CLOpt.mk_bool_group ~deprecated:["eradicate"] ~long:"eradicate"
-      "Activate the eradicate checker for java annotations"
+      "Activate the eradicate checker for Java annotations"
       [checkers] []
   in
   let quandary =
@@ -618,7 +618,7 @@ and checkers, crashcontext, eradicate, quandary, threadsafety, bufferoverrun =
       [checkers] []
   in
   let bufferoverrun =
-    CLOpt.mk_bool_group ~deprecated:["bufferoverrun"] ~long:"bufferoverrn"
+    CLOpt.mk_bool_group ~long:"bufferoverrun"
       "Activate the buffer overrun analysis"
       [checkers] []
   in
@@ -634,11 +634,12 @@ and clang_biniou_file =
 
 and clang_compilation_db_files =
   CLOpt.mk_path_list ~long:"clang-compilation-db-files"
-    "Files that contain compilation commands"
+    ~parse_mode:CLOpt.(Infer [Clang])
+    "File that contain compilation commands (can be specified multiple times)"
 
 and clang_frontend_action =
   CLOpt.mk_symbol_opt ~long:"clang-frontend-action"
-    ~parse_mode:CLOpt.(Infer [Clang;Driver])
+    ~parse_mode:CLOpt.(Infer [Clang])
     "Specify whether the clang frontend should capture or lint or both."
     ~symbols:clang_frontend_action_symbols
 
@@ -659,7 +660,7 @@ and cluster =
 and compute_analytics =
   CLOpt.mk_bool ~long:"compute-analytics"
     ~default:false
-    ~parse_mode:CLOpt.(Infer [Clang;Driver])
+    ~parse_mode:CLOpt.(Infer [Clang])
     "Emit analytics as info-level issues, like component kit line count and \
      component kit file cyclomatic complexity"
 
@@ -673,7 +674,7 @@ and continue =
 
 and linters_ignore_clang_failures =
   CLOpt.mk_bool ~long:"linters-ignore-clang-failures"
-    ~parse_mode:CLOpt.(Infer [Driver])
+    ~parse_mode:CLOpt.(Infer [Clang])
     ~default:false
     "Continue linting files even if some compilation fails."
 
@@ -743,7 +744,7 @@ and (
   in
   let debug =
     CLOpt.mk_bool_group ~deprecated:["debug"] ~long:"debug" ~short:"g"
-      ~parse_mode:CLOpt.(Infer [Analysis])
+      ~parse_mode:CLOpt.(Infer [Driver])
       "Debug mode (also sets --developer-mode, --no-filtering, --print-buckets, --print-types, \
        --reports-include-ml-loc, --no-test, --trace-error, --write-dotty, --write-html)"
       [developer_mode; print_buckets; print_types; reports_include_ml_loc; trace_error; write_html;
@@ -772,6 +773,7 @@ and (
   )
 and dependencies =
   CLOpt.mk_bool ~deprecated:["dependencies"] ~long:"dependencies"
+    ~parse_mode:CLOpt.(Infer [Java])
     "Translate all the dependencies during the capture. The classes in the given jar file will be \
      translated. No sources needed."
 
@@ -884,7 +886,7 @@ and frontend_tests =
 
 and generated_classes =
   CLOpt.mk_path_opt ~long:"generated-classes"
-    ~parse_mode:CLOpt.(Infer [Driver])
+    ~parse_mode:CLOpt.(Infer [Java])
     "Specify where to load the generated class files"
 
 and headers =
@@ -902,7 +904,7 @@ and infer_cache =
     ~meta:"dir" "Select a directory to contain the infer cache (Buck and Java only)"
 
 and iphoneos_target_sdk_version =
-  CLOpt.mk_string_opt ~long:"iphoneos-target-sdk-version" ~parse_mode:CLOpt.(Infer [Clang;Driver])
+  CLOpt.mk_string_opt ~long:"iphoneos-target-sdk-version" ~parse_mode:CLOpt.(Infer [Clang])
     "Specify the target SDK version to use for iphoneos"
 
 and iterations =
@@ -945,7 +947,7 @@ and load_average =
 
 and load_results =
   CLOpt.mk_path_opt ~deprecated:["load_results"] ~long:"load-results"
-    ~parse_mode:CLOpt.(Infer [Analysis])
+    ~parse_mode:CLOpt.(Infer [Print])
     ~meta:"file.iar" "Load analysis results from Infer Analysis Results file file.iar"
 
 (** name of the makefile to create with clusters and dependencies *)
@@ -1063,10 +1065,14 @@ and progress_bar =
     "Show a progress bar"
 
 and quandary_sources =
-  CLOpt.mk_json ~long:"quandary-sources" "Specify custom sources for Quandary"
+  CLOpt.mk_json ~long:"quandary-sources"
+    ~parse_mode:CLOpt.(Infer [Quandary])
+    "Specify custom sources for Quandary"
 
 and quandary_sinks =
-  CLOpt.mk_json ~long:"quandary-sinks" "Specify custom sinks for Quandary"
+  CLOpt.mk_json ~long:"quandary-sinks"
+    ~parse_mode:CLOpt.(Infer [Quandary])
+    "Specify custom sinks for Quandary"
 
 and quiet =
   CLOpt.mk_bool ~long:"quiet" ~short:"q" ~default:(current_exe <> Print)
@@ -1116,6 +1122,7 @@ and results_dir =
 
 and save_results =
   CLOpt.mk_path_opt ~deprecated:["save_results"] ~long:"save-results"
+    ~parse_mode:CLOpt.(Infer [Print])
     ~meta:"file.iar" "Save analysis results to Infer Analysis Results file file.iar"
 
 and seconds_per_iteration =
@@ -1179,13 +1186,13 @@ and specs_library =
   specs_library
 
 and stacktrace =
-  CLOpt.mk_path_opt ~long:"stacktrace" ~short:"st" ~parse_mode:CLOpt.(Infer [Driver])
+  CLOpt.mk_path_opt ~long:"stacktrace" ~short:"st" ~parse_mode:CLOpt.(Infer [Crashcontext])
     ~meta:"file" "File path containing a json-encoded Java crash stacktrace. Used to guide the \
                   analysis (only with '-a crashcontext').  See \
                   tests/codetoanalyze/java/crashcontext/*.json for examples of the expected format."
 
 and stacktraces_dir =
-  CLOpt.mk_path_opt ~long:"stacktraces-dir" ~parse_mode:CLOpt.(Infer [Driver])
+  CLOpt.mk_path_opt ~long:"stacktraces-dir" ~parse_mode:CLOpt.(Infer [Crashcontext])
     ~meta:"dir" "Directory path containing multiple json-encoded Java crash stacktraces. \
                  Used to guide the  analysis (only with '-a crashcontext').  See \
                  tests/codetoanalyze/java/crashcontext/*.json for examples of the expected format."
@@ -1236,7 +1243,7 @@ and type_size =
 
 and unsafe_malloc =
   CLOpt.mk_bool ~long:"unsafe-malloc"
-    ~parse_mode:CLOpt.(Infer [Analysis])
+    ~parse_mode:CLOpt.(Infer [Clang])
     "Assume that malloc(3) never returns null."
 
 and use_compilation_database =
@@ -1255,10 +1262,9 @@ and version =
     ~parse_mode:CLOpt.(Infer [Analysis;Clang;Driver;Print])
     "Print version information and exit" ;
   CLOpt.mk_set var `Json ~deprecated:["version_json"] ~long:"version-json"
-    ~parse_mode:CLOpt.(Infer [Analysis;Clang;Print])
+    ~parse_mode:CLOpt.(Infer [Analysis;Clang;Driver;Print])
     "Print version information in json format and exit" ;
   CLOpt.mk_set var `Vcs ~long:"version-vcs"
-    ~parse_mode:CLOpt.(Infer [Analysis;Clang;Print])
     "Print version control system commit and exit" ;
   var
 
@@ -1282,13 +1288,13 @@ and worklist_mode =
 
 and xcode_developer_dir =
   CLOpt.mk_path_opt ~long:"xcode-developer-dir"
-    ~parse_mode:CLOpt.(Infer [Driver])
+    ~parse_mode:CLOpt.(Infer [Clang])
     ~meta:"XCODE_DEVELOPER_DIR" "Specify the path to Xcode developer directory (Buck flavors only)"
 
 and xcpretty =
   CLOpt.mk_bool ~long:"xcpretty"
     ~default:true
-    ~parse_mode:CLOpt.(Infer [Driver])
+    ~parse_mode:CLOpt.(Infer [Clang])
     "Infer will use xcpretty together with xcodebuild to analyze an iOS app. xcpretty just needs \
      to be in the path, infer command is still just infer -- <xcodebuild command>. (Recommended)"
 

infer/src/base/Logging.ml

@@ -30,7 +30,7 @@ let dup_formatter fmt1 fmt2 =
 
 (** Name of dir for logging the output in the specific executable *)
 let log_dir_of_action (action : CLOpt.parse_action) = match action with
-  | Infer Analysis -> "analyze"
+  | Infer (Analysis | BufferOverrun | Crashcontext | Quandary) -> "analyze"
   | Infer Driver -> "driver"
   | Infer Clang
   | Infer Java