Java/C++/C#: Elaborate qldoc.

Author: aschackmull

cpp/ql/src/semmle/code/cpp/dataflow/internal/DataFlowUtil.qll

@@ -332,10 +332,18 @@ VariableAccess getAnAccessToAssignedVariable(Expr assign) {
   )
 }
 
-/** A guard that validates some expression. */
+/**
+ * A guard that validates some expression.
+ *
+ * To use this in a configuration, extend the class and provide a
+ * characteristic predicate precisely specifying the guard, and override
+ * `checks` to specify what is being validated and in which branch.
+ *
+ * It is important that all extending classes in scope are disjoint.
+ */
 class BarrierGuard extends Expr {
-  /** Holds if this guard validates `e` upon evaluating to `branch`. */
-  abstract predicate checks(Expr e, boolean branch);
+  /** NOT YET SUPPORTED. Holds if this guard validates `e` upon evaluating to `branch`. */
+  abstract deprecated predicate checks(Expr e, boolean branch);
 
   /** Gets a node guarded by this. */
   final Node getAGuardedNode() {

cpp/ql/src/semmle/code/cpp/ir/dataflow/internal/DataFlowUtil.qll

@@ -168,10 +168,18 @@ predicate localFlowStep(Node nodeFrom, Node nodeTo) {
  */
 predicate localFlow(Node source, Node sink) { localFlowStep*(source, sink) }
 
-/** A guard that validates some expression. */
+/**
+ * A guard that validates some expression.
+ *
+ * To use this in a configuration, extend the class and provide a
+ * characteristic predicate precisely specifying the guard, and override
+ * `checks` to specify what is being validated and in which branch.
+ *
+ * It is important that all extending classes in scope are disjoint.
+ */
 class BarrierGuard extends IRGuardCondition {
-  /** Holds if this guard validates `e` upon evaluating to `b`. */
-  abstract predicate checks(Instruction e, boolean b);
+  /** NOT YET SUPPORTED. Holds if this guard validates `e` upon evaluating to `b`. */
+  abstract deprecated predicate checks(Instruction e, boolean b);
 
   /** Gets a node guarded by this. */
   final Node getAGuardedNode() {

csharp/ql/src/semmle/code/csharp/dataflow/internal/DataFlowPublic.qll

@@ -164,10 +164,18 @@ abstract class NonLocalJumpNode extends Node {
   abstract Node getAJumpSuccessor(boolean preservesValue);
 }
 
-/** A guard that validates some expression. */
+/**
+ * A guard that validates some expression.
+ *
+ * To use this in a configuration, extend the class and provide a
+ * characteristic predicate precisely specifying the guard, and override
+ * `checks` to specify what is being validated and in which branch.
+ *
+ * It is important that all extending classes in scope are disjoint.
+ */
 class BarrierGuard extends Internal::Guard {
-  /** Holds if this guard validates `e` upon evaluating to `v`. */
-  abstract predicate checks(Expr e, AbstractValue v);
+  /** NOT YET SUPPORTED. Holds if this guard validates `e` upon evaluating to `v`. */
+  abstract deprecated predicate checks(Expr e, AbstractValue v);
 
   /** Gets a node guarded by this. */
   final Node getAGuardedNode() {

java/ql/src/semmle/code/java/dataflow/internal/DataFlowUtil.qll

@@ -418,7 +418,15 @@ Node getInstanceArgument(Call call) {
   implicitInstanceArgument(call, result.(ImplicitInstanceAccess).getInstanceAccess())
 }
 
-/** A guard that validates some expression. */
+/**
+ * A guard that validates some expression.
+ *
+ * To use this in a configuration, extend the class and provide a
+ * characteristic predicate precisely specifying the guard, and override
+ * `checks` to specify what is being validated and in which branch.
+ *
+ * It is important that all extending classes in scope are disjoint.
+ */
 class BarrierGuard extends Guard {
   /** Holds if this guard validates `e` upon evaluating to `branch`. */
   abstract predicate checks(Expr e, boolean branch);