C++: Try to improve QLDoc on deconstructSizeExpr.

geoffw0 · geoffw0 · commit 49076773514d · 2020-05-01T14:26:33.000+01:00
diff --git a/cpp/ql/src/semmle/code/cpp/models/implementations/Allocation.qll b/cpp/ql/src/semmle/code/cpp/models/implementations/Allocation.qll
@@ -271,12 +271,15 @@ class OperatorNewAllocationFunction extends AllocationFunction {
 }
 
 /**
- * The predicate analyzes a `sizeExpr`, which is an argument to an allocation
- * function like malloc, and tries to split it into an expression `lengthExpr`
- * that describes the length of the allocated array, and the size of the allocated
- * element type `sizeof`.
- * If this is not possible, the allocation is considered to be of size 1 and of
- * length `sizeExpr`.
+ * Holds if `sizeExpr` is an expression consisting of a subexpression
+ * `lengthExpr` multiplied by a constant `sizeof` that is the result of a
+ * `sizeof()` expression.  Alternatively if there isn't a suitable `sizeof()`
+ * expression, `lengthExpr = sizeExpr` and `sizeof = 1`.  For example:
+ * ```
+ * malloc(a * 2 * sizeof(char32_t));
+ * ```
+ * In this case if the `sizeExpr` is the argument to `malloc`, the `lengthExpr`
+ * is `a * 2` and `sizeof` is `4`.
  */
 private predicate deconstructSizeExpr(Expr sizeExpr, Expr lengthExpr, int sizeof) {
   if
