[doc] Add documentation for hoisting and invariant calls

Reviewed By: skcho

Differential Revision: D22090818

fbshipit-source-id: 86c4bdaf9

infer/documentation/checkers/LoopHoisting.md

@@ -0,0 +1,3 @@
+This checker detects opportunities to hoist function calls that are invariant to outside of loop bodies. The hoisting analysis relies on [purity](/docs/next/checker-purity) analysis to determine whather a function is pure or not.
+
+It has an additional mode that reports [loop-invariant functions that are expensive](/docs/next/all-issue-types#expensive_loop_invariant_call) (i.e. at least linear). This is enabled by the flag `--hoisting-report-only-expensive`.

infer/documentation/issues/EXPENSIVE_LOOP_INVARIANT_CALL.md

@@ -0,0 +1,22 @@
+We report this issue type when a function is [loop-invariant](/docs/next/all-issue-types#invariant_call) and also expensive (i.e. at least has linear complexity as determined by the [cost](/docs/next/checker-cost) analysis).
+
+```java
+int incr(int x) {
+  return x + 1;
+}
+
+// incr will not be hoisted since it is cheap(constant time)
+void foo_linear(int size) {
+  int x = 10;
+  for (int i = 0; i < size; i++) {
+    incr(x); // constant call, don't hoist
+  }
+}
+
+// call to foo_linear will be hoisted since it is expensive(linear in size).
+void symbolic_expensive_hoist(int size) {
+  for (int i = 0; i < size; i++) {
+    foo_linear(size); // hoist
+  }
+}
+```

infer/documentation/issues/INVARIANT_CALL.md

@@ -0,0 +1,19 @@
+We report this issue type when a function call is loop-invariant and hoistable, i.e.
+- the function has no side side effects (pure)
+- has invariant arguments and result (i.e. have the same value in all loop iterations)
+- it is guaranteed to execute, i.e. it dominates all loop sources
+
+```java
+int foo(int x, int y) {
+ return x + y;
+}
+
+
+void invariant_hoist(int size) {
+    int x = 10;
+    int y = 5;
+    for (int i = 0; i < size; i++) {
+      foo(x, y); // hoistable
+    }
+  }
+```

infer/src/base/Checker.ml

@@ -238,7 +238,10 @@ let config_unsafe checker =
       ; activates= [] }
   | LoopHoisting ->
       { id= "loop-hoisting"
-      ; kind= UserFacing {title= "Loop Hoisting"; markdown_body= ""}
+      ; kind=
+          UserFacing
+            { title= "Loop Hoisting"
+            ; markdown_body= [%blob "../../documentation/checkers/LoopHoisting.md"] }
       ; support= supports_clang_and_java
       ; short_documentation=
           "Detect opportunities to hoist function calls that are invariant outside of loop bodies \

infer/src/base/IssueType.ml

@@ -700,7 +700,10 @@ let internal_error =
   register_from_string ~visibility:Developer ~id:"Internal_error" Error Biabduction
 
 
-let invariant_call = register_from_string ~enabled:false ~id:"INVARIANT_CALL" Error LoopHoisting
+let invariant_call =
+  register_from_string ~enabled:false ~id:"INVARIANT_CALL" Error LoopHoisting
+    ~user_documentation:[%blob "../../documentation/issues/INVARIANT_CALL.md"]
+
 
 let javascript_injection =
   register_from_string ~id:"JAVASCRIPT_INJECTION" Error Quandary
@@ -738,6 +741,7 @@ let logging_private_data =
 
 let expensive_loop_invariant_call =
   register_from_string ~id:"EXPENSIVE_LOOP_INVARIANT_CALL" Error LoopHoisting
+    ~user_documentation:[%blob "../../documentation/issues/EXPENSIVE_LOOP_INVARIANT_CALL.md"]
 
 
 let memory_leak =