Merge branch 'master' into ir-flow-fields

Author: MathiasVP

cpp/ql/src/Critical/FileClosed.qll

@@ -1,5 +1,6 @@
 import semmle.code.cpp.pointsto.PointsTo
 
+/** Holds if there exists a call to a function that might close the file specified by `e`. */
 predicate closed(Expr e) {
   fcloseCall(_, e) or
   exists(ExprCall c |
@@ -8,10 +9,19 @@ predicate closed(Expr e) {
   )
 }
 
+/** An expression for which there exists a function call that might close it. */
 class ClosedExpr extends PointsToExpr {
   ClosedExpr() { closed(this) }
 
   override predicate interesting() { closed(this) }
 }
 
+/**
+ * Holds if `fc` is a call to a function that opens a file that might be closed. For example:
+ * ```
+ * FILE* f = fopen("file.txt", "r");
+ * ...
+ * fclose(f);
+ * ```
+ */
 predicate fopenCallMayBeClosed(FunctionCall fc) { fopenCall(fc) and anythingPointsTo(fc) }

cpp/ql/src/Critical/LoopBounds.qll

@@ -2,12 +2,24 @@
 
 import cpp
 
+/**
+ * An assignment to a variable with the value `0`. For example:
+ * ```
+ * int x;
+ * x = 0;
+ * ```
+ * but not:
+ * ```
+ * int x = 0;
+ * ```
+ */
 class ZeroAssignment extends AssignExpr {
   ZeroAssignment() {
     this.getAnOperand() instanceof VariableAccess and
     this.getAnOperand() instanceof Zero
   }
 
+  /** Gets a variable that is assigned the value `0`. */
   Variable assignedVariable() { result.getAnAccess() = this.getAnOperand() }
 }
 

cpp/ql/src/Critical/MemoryFreed.qll

@@ -9,10 +9,19 @@ private predicate freed(Expr e) {
   )
 }
 
+/** An expression that might be deallocated. */
 class FreedExpr extends PointsToExpr {
   FreedExpr() { freed(this) }
 
   override predicate interesting() { freed(this) }
 }
 
+/**
+ * An allocation expression that might be deallocated. For example:
+ * ```
+ * int* p = new int;
+ * ...
+ * delete p;
+ * ```
+ */
 predicate allocMayBeFreed(AllocationExpr alloc) { anythingPointsTo(alloc) }

cpp/ql/src/JPL_C/LOC-3/Rule 17/BasicIntTypes.ql

@@ -30,7 +30,7 @@ predicate allowedTypedefs(TypedefType t) {
  * Gets a type which appears literally in the declaration of `d`.
  */
 Type getAnImmediateUsedType(Declaration d) {
-  d.isDefined() and
+  d.hasDefinition() and
   (
     result = d.(Function).getType() or
     result = d.(Variable).getType()

cpp/ql/src/Options.qll

@@ -4,7 +4,7 @@
  *
  * By default they fall back to the reasonable defaults provided in
  * `DefaultOptions.qll`, but by modifying this file, you can customize
- * the standard Semmle analyses to give better results for your project.
+ * the standard analyses to give better results for your project.
  */
 
 import cpp

cpp/ql/src/Security/CWE/CWE-457/InitializationFunctions.qll

@@ -198,12 +198,12 @@ class InitializationFunction extends Function {
     )
     or
     // If we have no definition, we look at SAL annotations
-    not this.isDefined() and
+    not this.hasDefinition() and
     this.getParameter(i).(SALParameter).isOut() and
     evidence = SuggestiveSALAnnotation()
     or
     // We have some external information that this function conditionally initializes
-    not this.isDefined() and
+    not this.hasDefinition() and
     any(ValidatedExternalCondInitFunction vc).isExternallyVerified(this, i) and
     evidence = ExternalEvidence()
   }
@@ -406,7 +406,7 @@ class ConditionalInitializationFunction extends InitializationFunction {
        * Explicitly ignore pure virtual functions.
        */
 
-      this.isDefined() and
+      this.hasDefinition() and
       this.paramNotReassignedAt(this, i, c) and
       not this instanceof PureVirtualFunction
     )
@@ -616,11 +616,11 @@ private predicate functionSignature(Function f, string qualifiedName, string typ
  * are never statically linked together.
  */
 private Function getAPossibleDefinition(Function undefinedFunction) {
-  not undefinedFunction.isDefined() and
+  not undefinedFunction.hasDefinition() and
   exists(string qn, string typeSig |
     functionSignature(undefinedFunction, qn, typeSig) and functionSignature(result, qn, typeSig)
   ) and
-  result.isDefined()
+  result.hasDefinition()
 }
 
 /**
@@ -631,7 +631,7 @@ private Function getAPossibleDefinition(Function undefinedFunction) {
  */
 private Function getTarget1(Call c) {
   result = VirtualDispatch::getAViableTarget(c) and
-  result.isDefined()
+  result.hasDefinition()
 }
 
 /**

cpp/ql/src/semmle/code/cpp/Compilation.qll

@@ -21,9 +21,9 @@ private predicate idOf(@compilation x, int y) = equivalenceRelation(id/2)(x, y)
  * Three things happen to each file during a compilation:
  *
  *   1. The file is compiled by a real compiler, such as gcc or VC.
- *   2. The file is parsed by Semmle's C++ front-end.
+ *   2. The file is parsed by the CodeQL C++ front-end.
  *   3. The parsed representation is converted to database tables by
- *      Semmle's extractor.
+ *      the CodeQL extractor.
  *
  * This class provides CPU and elapsed time information for steps 2 and 3,
  * but not for step 1.

cpp/ql/src/semmle/code/cpp/Declaration.qll

@@ -161,6 +161,7 @@ abstract class Declaration extends Locatable, @declaration {
   /** Holds if the declaration has a definition. */
   predicate hasDefinition() { exists(this.getDefinition()) }
 
+  /** DEPRECATED: Use `hasDefinition` instead. */
   predicate isDefined() { hasDefinition() }
 
   /** Gets the preferred location of this declaration, if any. */
@@ -303,7 +304,7 @@ abstract class DeclarationEntry extends Locatable {
    * available), or the name declared by this entry otherwise.
    */
   string getCanonicalName() {
-    if getDeclaration().isDefined()
+    if getDeclaration().hasDefinition()
     then result = getDeclaration().getDefinition().getName()
     else result = getName()
   }

cpp/ql/src/semmle/code/cpp/UserType.qll

@@ -38,7 +38,7 @@ class UserType extends Type, Declaration, NameQualifyingElement, AccessHolder, @
   override Specifier getASpecifier() { result = Type.super.getASpecifier() }
 
   override Location getLocation() {
-    if isDefined()
+    if hasDefinition()
     then result = this.getDefinitionLocation()
     else result = this.getADeclarationLocation()
   }

cpp/ql/src/semmle/code/cpp/dataflow/RecursionPrevention.qll

@@ -1,6 +1,6 @@
 /**
  * DEPRECATED: Recursion through `DataFlow::Configuration` is impossible in
- * Semmle Core 1.17 and above. There is no need for this module because it's
+ * any supported tooling. There is no need for this module because it's
  * impossible to accidentally depend on recursion through
  * `DataFlow::Configuration` in current releases.
  *