Java: Extend qldoc.

Author: aschackmull

java/ql/lib/semmle/code/java/controlflow/SuccessorType.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides different types of control flow successor types.
+ */
+
 import java
 private import codeql.util.Boolean
 
@@ -6,20 +10,62 @@ private newtype TSuccessorType =
   TBooleanSuccessor(Boolean branch) or
   TExceptionSuccessor()
 
+/** The type of a control flow successor. */
 class SuccessorType extends TSuccessorType {
   string toString() { result = "SuccessorType" }
 }
 
+/** A normal control flow successor. */
 class NormalSuccessor extends SuccessorType, TNormalSuccessor { }
 
+/**
+ * An exceptional control flow successor.
+ *
+ * This marks control flow edges that are taken when an exception is thrown.
+ */
 class ExceptionSuccessor extends SuccessorType, TExceptionSuccessor { }
 
+/**
+ * A conditional control flow successor.
+ *
+ * This currently only includes boolean successors (`BooleanSuccessor`).
+ */
 class ConditionalSuccessor extends SuccessorType, TBooleanSuccessor {
+  /** Gets the Boolean value of this successor. */
   boolean getValue() { this = TBooleanSuccessor(result) }
 }
 
+/**
+ * A Boolean control flow successor.
+ *
+ * For example, this program fragment:
+ *
+ * ```java
+ * if (x < 0)
+ *     return 0;
+ * else
+ *     return 1;
+ * ```
+ *
+ * has a control flow graph containing Boolean successors:
+ *
+ * ```
+ *        if
+ *        |
+ *      x < 0
+ *       / \
+ *      /   \
+ *     /     \
+ *  true    false
+ *    |        \
+ * return 0   return 1
+ * ```
+ */
 class BooleanSuccessor = ConditionalSuccessor;
 
+/**
+ * A nullness control flow successor. This is currently unused for Java.
+ */
 class NullnessSuccessor extends ConditionalSuccessor {
   NullnessSuccessor() { none() }
 }