C++: add docstrings to Printf and BufferWrite

redsun82 · web-flow · commit fb03561a3100 · 2021-12-13T11:28:02.000Z
diff --git a/cpp/ql/lib/semmle/code/cpp/commons/Printf.qll b/cpp/ql/lib/semmle/code/cpp/commons/Printf.qll
@@ -1021,6 +1021,11 @@ class FormatLiteral extends Literal {
    */
   int getMaxConvertedLength(int n) { result = max(int l | l = getMaxConvertedLength(n, _) | l) }
 
+  /**
+   * Gets the maximum length of the string that can be produced by the nth
+   * conversion specifier of this format string, specifying the estimation reason;
+   * has no result if this cannot be determined. 
+   */
   int getMaxConvertedLength(int n, BufferWriteEstimationReason reason) {
     exists(int len |
       (
@@ -1238,6 +1243,13 @@ class FormatLiteral extends Literal {
     result = max(int l | l = getMaxConvertedLengthLimited(n, _) | l)
   }
 
+  /**
+   * Gets the maximum length of the string that can be produced by the nth
+   * conversion specifier of this format string, specifying the reason for the
+   * estimation, except that float to string conversions are assumed to be 8
+   * characters.  This is helpful for determining whether a buffer overflow is
+   * caused by long float to string conversions.
+   */
   int getMaxConvertedLengthLimited(int n, BufferWriteEstimationReason reason) {
     if this.getConversionChar(n).toLowerCase() = "f"
     then result = this.getMaxConvertedLength(n, reason).minimum(8)
@@ -1319,10 +1331,21 @@ class FormatLiteral extends Literal {
    */
   int getMaxConvertedLengthLimited() { result = this.getMaxConvertedLengthAfterLimited(0, _) }
 
+  /**
+   * Gets the maximum length of the string that can be produced by this format
+   * string, specifying the reason for the estimate. Has no result if no estimate
+   * can be found.
+   */
   int getMaxConvertedLengthWithReason(BufferWriteEstimationReason reason) {
     result = this.getMaxConvertedLengthAfter(0, reason)
   }
 
+  /**
+   * Gets the maximum length of the string that can be produced by this format
+   * string, specifying the reason for the estimate, except that float to string
+   * conversions are assumed to be 8 characters.  This is helpful for determining
+   * whether a buffer overflow is caused by long float to string conversions.
+   */
   int getMaxConvertedLengthLimitedWithReason(BufferWriteEstimationReason reason) {
     result = this.getMaxConvertedLengthAfterLimited(0, reason)
   }
diff --git a/cpp/ql/lib/semmle/code/cpp/security/BufferWrite.qll b/cpp/ql/lib/semmle/code/cpp/security/BufferWrite.qll
@@ -79,8 +79,19 @@ abstract class BufferWrite extends Expr {
    */
   int getMaxDataLimited() { result = max(int d | d = getMaxDataLimited(_) | d) }
 
+  /**
+   * Gets an upper bound to the amount of data that's being written (if one
+   * can be found), specifying the reason for the estimation
+   */
   int getMaxData(BufferWriteEstimationReason reason) { none() }
 
+  /**
+   * Gets an upper bound to the amount of data that's being written (if one
+   * can be found), specifying the reason for the estimation, except that
+   * float to string conversions are assumed to be much smaller (8 bytes)
+   * than their true maximum length.  This can be helpful in determining the
+   * cause of a buffer overflow issue.
+   */
   int getMaxDataLimited(BufferWriteEstimationReason reason) { result = getMaxData(reason) }
 
   /**
