C++: Attempt to clarify the way Allocation.qll and Deallocation.qll should be used.

Author: geoffw0

cpp/ql/lib/semmle/code/cpp/models/interfaces/Allocation.qll

@@ -12,27 +12,38 @@ import semmle.code.cpp.Function
 import semmle.code.cpp.models.Models
 
 /**
- * An allocation function such as `malloc`.
+ * An allocation expression such as call to `malloc` or a `new` expression.
  */
-abstract class AllocationFunction extends Function {
+abstract class AllocationExpr extends Expr {
   /**
-   * Gets the index of the argument for the allocation size, if any. The actual
-   * allocation size is the value of this argument multiplied by the result of
+   * Gets an expression for the allocation size, if any. The actual allocation
+   * size is the value of this expression multiplied by the result of
    * `getSizeMult()`, in bytes.
    */
-  int getSizeArg() { none() }
+  Expr getSizeExpr() { none() }
 
   /**
-   * Gets the index of an argument that multiplies the allocation size given by
-   * `getSizeArg`, if any.
+   * Gets a constant multiplier for the allocation size given by `getSizeExpr`,
+   * in bytes.
    */
   int getSizeMult() { none() }
 
   /**
-   * Gets the index of the input pointer argument to be reallocated, if this
-   * is a `realloc` function.
+   * Gets the size of this allocation in bytes, if it is a fixed size and that
+   * size can be determined.
    */
-  int getReallocPtrArg() { none() }
+  int getSizeBytes() { none() }
+
+  /**
+   * Gets the expression for the input pointer argument to be reallocated, if
+   * this is a `realloc` function.
+   */
+  Expr getReallocPtr() { none() }
+
+  /**
+   * Gets the type of the elements that are allocated, if it can be determined.
+   */
+  Type getAllocatedElementType() { none() }
 
   /**
    * Whether or not this allocation requires a corresponding deallocation of
@@ -44,38 +55,30 @@ abstract class AllocationFunction extends Function {
 }
 
 /**
- * An allocation expression such as call to `malloc` or a `new` expression.
+ * An allocation function such as `malloc`.
+ *
+ * Note: `AllocationExpr` includes calls to allocation functions, so prefer
+ * to use that class unless you specifically need to reason about functions.
  */
-abstract class AllocationExpr extends Expr {
+abstract class AllocationFunction extends Function {
   /**
-   * Gets an expression for the allocation size, if any. The actual allocation
-   * size is the value of this expression multiplied by the result of
+   * Gets the index of the argument for the allocation size, if any. The actual
+   * allocation size is the value of this argument multiplied by the result of
    * `getSizeMult()`, in bytes.
    */
-  Expr getSizeExpr() { none() }
+  int getSizeArg() { none() }
 
   /**
-   * Gets a constant multiplier for the allocation size given by `getSizeExpr`,
-   * in bytes.
+   * Gets the index of an argument that multiplies the allocation size given by
+   * `getSizeArg`, if any.
    */
   int getSizeMult() { none() }
 
   /**
-   * Gets the size of this allocation in bytes, if it is a fixed size and that
-   * size can be determined.
-   */
-  int getSizeBytes() { none() }
-
-  /**
-   * Gets the expression for the input pointer argument to be reallocated, if
-   * this is a `realloc` function.
-   */
-  Expr getReallocPtr() { none() }
-
-  /**
-   * Gets the type of the elements that are allocated, if it can be determined.
+   * Gets the index of the input pointer argument to be reallocated, if this
+   * is a `realloc` function.
    */
-  Type getAllocatedElementType() { none() }
+  int getReallocPtrArg() { none() }
 
   /**
    * Whether or not this allocation requires a corresponding deallocation of

cpp/ql/lib/semmle/code/cpp/models/interfaces/Deallocation.qll

@@ -12,23 +12,26 @@ import semmle.code.cpp.Function
 import semmle.code.cpp.models.Models
 
 /**
- * A deallocation function such as `free`.
+ * An deallocation expression such as call to `free` or a `delete` expression.
  */
-abstract class DeallocationFunction extends Function {
+abstract class DeallocationExpr extends Expr {
   /**
-   * Gets the index of the argument that is freed by this function.
+   * Gets the expression that is freed by this function.
    */
-  int getFreedArg() { none() }
+  Expr getFreedExpr() { none() }
 }
 
 /**
- * An deallocation expression such as call to `free` or a `delete` expression.
+ * A deallocation function such as `free`.
+ *
+ * Note: `DeallocationExpr` includes calls to deallocation functions, so prefer
+ * to use that class unless you specifically need to reason about functions.
  */
-abstract class DeallocationExpr extends Expr {
+abstract class DeallocationFunction extends Function {
   /**
-   * Gets the expression that is freed by this function.
+   * Gets the index of the argument that is freed by this function.
    */
-  Expr getFreedExpr() { none() }
+  int getFreedArg() { none() }
 }
 
 /**