update documentation of ARBITRARY_CODE_EXECUTION_UNDER_LOCK

Summary:
Minor improvements to the text as an exercise to improve error messages
in general in the future.

Reviewed By: ngorogiannis

Differential Revision: D31610147

fbshipit-source-id: eda8f916c

Author: jvillard

infer/documentation/issues/ARBITRARY_CODE_EXECUTION_UNDER_LOCK.md

@@ -1,24 +1,25 @@
-A call which may execute arbitrary code (such as registered, or chained, callbacks) is made while a lock is held.
+A call that may execute arbitrary code (such as registered, or chained, callbacks) is made while holding a lock.
 This code may deadlock whenever the callbacks obtain locks themselves, so it is an unsafe pattern.
-This warning is issued only at the innermost lock acquisition around the final call.
 
 Example:
 ```java
-public class NotUnderLock {
   SettableFuture future = null;
 
-  public void callFutureSetOk() {
+  public void callFutureSet() {
     future.set(null);
   }
 
-  public synchronized void firstAcquisitionBad() {
-    callFutureSetOk();
+  // synchronized means it's taking a lock implicitly
+  public synchronized void example_of_bad_pattern() {
+    callFutureSet(); // <- issue reported here
   }
 
-  public void secondAcquisitionOk(Object o) {
+  // If the call is made while holding multiple locks, the warning
+  // will be issued only at the innermost lock acquisition. Here we
+  // report in example_of_bad_pattern but we won't report below.
+  public void nested_bad_pattern_no_report(Object o) {
     synchronized (o) {
-      firstAcquisitionBad();
+      example_of_bad_pattern(); // <- no issue reported
     }
   }
-}
 ```

website/docs/all-issue-types.md

@@ -9,29 +9,30 @@ Here is an overview of the issue types currently reported by Infer.
 
 Reported as "Arbitrary Code Execution Under lock" by [starvation](/docs/next/checker-starvation).
 
-A call which may execute arbitrary code (such as registered, or chained, callbacks) is made while a lock is held.
+A call that may execute arbitrary code (such as registered, or chained, callbacks) is made while holding a lock.
 This code may deadlock whenever the callbacks obtain locks themselves, so it is an unsafe pattern.
-This warning is issued only at the innermost lock acquisition around the final call.
 
 Example:
 ```java
-public class NotUnderLock {
   SettableFuture future = null;
 
-  public void callFutureSetOk() {
+  public void callFutureSet() {
     future.set(null);
   }
 
-  public synchronized void firstAcquisitionBad() {
-    callFutureSetOk();
+  // synchronized means it's taking a lock implicitly
+  public synchronized void example_of_bad_pattern() {
+    callFutureSet(); // <- issue reported here
   }
 
-  public void secondAcquisitionOk(Object o) {
+  // If the call is made while holding multiple locks, the warning
+  // will be issued only at the innermost lock acquisition. Here we
+  // report in example_of_bad_pattern but we won't report below.
+  public void nested_bad_pattern_no_report(Object o) {
     synchronized (o) {
-      firstAcquisitionBad();
+      example_of_bad_pattern(); // <- no issue reported
     }
   }
-}
 ```
 
 ## ASSIGN_POINTER_WARNING