Shared: Generate some QLDoc using the "GitHub Copilot: Generate Docs" command.

shared/dataflow/codeql/dataflow/DataFlow.qll

@@ -6,21 +6,24 @@
 
 /** Provides language-specific data flow parameters. */
 signature module InputSig {
-  class Node {
-    /** Gets a textual representation of this element. */
-    string toString();
-
-    /**
-     * Holds if this element is at the specified location.
-     * The location spans column `startcolumn` of line `startline` to
-     * column `endcolumn` of line `endline` in file `filepath`.
-     * For more information, see
-     * [Locations](https://codeql.github.com/docs/writing-codeql-queries/providing-locations-in-codeql-queries/).
+  /**
+     * Represents a node in the data flow graph.
      */
-    predicate hasLocationInfo(
-      string filepath, int startline, int startcolumn, int endline, int endcolumn
-    );
-  }
+    class Node {
+      /** Gets a textual representation of this element. */
+      string toString();
+
+      /**
+       * Holds if this element is at the specified location.
+       * The location spans column `startcolumn` of line `startline` to
+       * column `endcolumn` of line `endline` in file `filepath`.
+       * For more information, see
+       * [Locations](https://codeql.github.com/docs/writing-codeql-queries/providing-locations-in-codeql-queries/).
+       */
+      predicate hasLocationInfo(
+        string filepath, int startline, int startcolumn, int endline, int endcolumn
+      );
+    }
 
   class ParameterNode extends Node;
 
@@ -30,9 +33,19 @@ signature module InputSig {
     ReturnKind getKind();
   }
 
+  /**
+   * Represents a node in the data flow graph that represents an output.
+   */
   class OutNode extends Node;
 
+  /**
+   * Represents a node in the data flow graph that corresponds to a post-update operation.
+   */
   class PostUpdateNode extends Node {
+    /**
+     * Retrieves the node that represents the pre-update operation.
+     * @return The pre-update node.
+     */
     Node getPreUpdateNode();
   }
 
@@ -131,6 +144,12 @@ signature module InputSig {
     string toString();
   }
 
+  /**
+   * Predicate to force high precision for the given content.
+   *
+   * @param c The content to force high precision for.
+   * @return True if high precision is forced for the content, false otherwise.
+   */
   predicate forceHighPrecision(Content c);
 
   /**
@@ -150,10 +169,16 @@ signature module InputSig {
     Content getAReadContent();
   }
 
-  class ContentApprox {
-    /** Gets a textual representation of this element. */
-    string toString();
-  }
+  /**
+     * Represents a content approximation.
+     */
+    class ContentApprox {
+      /** 
+       * Gets a textual representation of this element.
+       * @return The textual representation of this element.
+       */
+      string toString();
+    }
 
   ContentApprox getContentApprox(Content c);
 
@@ -169,8 +194,22 @@ signature module InputSig {
     string toString();
   }
 
+  /**
+   * Checks if the given parameter position matches the argument position.
+   *
+   * @param ppos The parameter position.
+   * @param apos The argument position.
+   * @return True if the parameter position matches the argument position, false otherwise.
+   */
   predicate parameterMatch(ParameterPosition ppos, ArgumentPosition apos);
 
+  /**
+   * Represents a simple local flow step between two nodes.
+   *
+   * @param node1 The first node in the flow step.
+   * @param node2 The second node in the flow step.
+   * @return True if there is a simple local flow step between node1 and node2, false otherwise.
+   */
   predicate simpleLocalFlowStep(Node node1, Node node2);
 
   /**

shared/rangeanalysis/codeql/rangeanalysis/RangeAnalysis.qll

@@ -160,17 +160,49 @@ signature module Semantic {
   /** Gets a tiebreaker id in case `getBlockId1` is not unique. */
   default string getBlockId2(BasicBlock bb) { result = "" }
 
+  /**
+   * Represents a guard in the range analysis.
+   */
   class Guard {
+    /**
+     * Returns a string representation of the guard.
+     */
     string toString();
 
+    /**
+     * Returns the basic block associated with the guard.
+     */
     BasicBlock getBasicBlock();
 
+    /**
+     * Returns the guard as an expression.
+     */
     Expr asExpr();
 
+    /**
+     * Checks if the guard directly controls a given basic block.
+     * @param controlled The basic block to check.
+     * @param branch Indicates if the control is a branch or not.
+     * @returns True if the guard directly controls the basic block, false otherwise.
+     */
     predicate directlyControls(BasicBlock controlled, boolean branch);
 
+    /**
+     * Checks if the guard represents an equality between two expressions.
+     * @param e1 The first expression.
+     * @param e2 The second expression.
+     * @param polarity The polarity of the equality.
+     * @returns True if the guard represents the equality, false otherwise.
+     */
     predicate isEquality(Expr e1, Expr e2, boolean polarity);
 
+    /**
+     * Checks if there is a branch edge between two basic blocks.
+     * @param bb1 The first basic block.
+     * @param bb2 The second basic block.
+     * @param branch Indicates if the edge is a branch or not.
+     * @returns True if there is a branch edge between the basic blocks, false otherwise.
+     */
     predicate hasBranchEdge(BasicBlock bb1, BasicBlock bb2, boolean branch);
   }
 
@@ -194,18 +226,43 @@ signature module Semantic {
   /** Gets the type of an expression. */
   Type getExprType(Expr e);
 
+  /**
+   * Represents a single static single assignment (SSA) variable.
+   */
   class SsaVariable {
+    /**
+     * Returns the expression where this SSA variable is used.
+     */
     Expr getAUse();
 
+    /**
+     * Returns the basic block where this SSA variable is defined.
+     */
     BasicBlock getBasicBlock();
   }
 
+  /**
+   * Represents a phi node in the SSA form.
+   */
   class SsaPhiNode extends SsaVariable {
-    /** Holds if `inp` is an input to the phi node along the edge originating in `bb`. */
+    /**
+     * Holds if `inp` is an input to the phi node along the edge originating in `bb`.
+     * @param inp The input variable.
+     * @param bb The basic block.
+     * @return True if `inp` is an input to the phi node along the edge originating in `bb`, false otherwise.
+     */
     predicate hasInputFromBlock(SsaVariable inp, BasicBlock bb);
   }
 
+  /**
+   * Represents a single update to a variable in the SSA form.
+   */
   class SsaExplicitUpdate extends SsaVariable {
+    /**
+     * Retrieves the expression that defines the value of the variable in this update.
+     *
+     * @return The defining expression.
+     */
     Expr getDefiningExpr();
   }
 
@@ -296,11 +353,24 @@ signature module LangSig<Semantic Sem, DeltaSig D> {
 }
 
 signature module BoundSig<LocationSig Location, Semantic Sem, DeltaSig D> {
+  /**
+   * Represents a semantic bound.
+   */
   class SemBound {
+    /**
+     * Returns a string representation of the semantic bound.
+     */
     string toString();
 
+    /**
+     * Returns the location of the semantic bound.
+     */
     Location getLocation();
 
+    /**
+     * Returns the expression associated with the semantic bound, given a delta.
+     * @param delta - The delta value.
+     */
     Sem::Expr getExpr(D::Delta delta);
   }