Shared: Elaborate qldoc.

Author: aschackmull

shared/controlflow/codeql/controlflow/Guards.qll

@@ -23,9 +23,29 @@
  * }
  * ```
  *
+ * The provided predicates are separated into general "controls" predicates and
+ * "directly controls" predicates. The former use all possible implication
+ * logic as described above, whereas the latter only use control flow dominance
+ * of the corresponding conditional successor edges.
+ *
+ * In some cases, a guard may have a successor edge that can be relevant for
+ * controlling the input to an SSA phi node, but does not dominate the
+ * preceeding block. To support this, the `hasBranchEdge` and
+ * `controlsBranchEdge` predicates are provided, where the former only uses the
+ * control flow graph similar to the `directlyControls` predicate, and the
+ * latter uses the full implication logic.
+ *
+ * All of these predicates are also available in the more general form that refers
+ * to `GuardValue`s instead of `boolean`s.
+ *
  * The implementation is nested in two parameterized modules intended to
  * facilitate multiple instantiations of the nested module with different
- * precision levels
+ * precision levels. For example, more implications are available if the result
+ * of Range Analysis is available, but Range Analysis depends on Guards. This
+ * allows an initial instantiation of the `Logic` module without Range Analysis
+ * that can be used as input to Range Analysis, and a second instantiation
+ * using the result of Range Analysis to provide a final and more complete
+ * controls relation.
  */
 
 private import codeql.util.Boolean