C++: Don't use @param in QLDoc

jbj · jbj · commit 64e227790453 · 2019-09-09T11:04:04.000+02:00
It superficially looks like `@param` is supported in QLDoc, but this is
mostly an accident of how its parser works. Attributes starting with `@`
are only intended to be used in the top-level QLDoc of a query, and
there can only be one of each attribute. If there are multiple `@param`
entries, the QLDoc parser will only keep the first one.

Even though `parseConvSpec` in `Scanf.qll` documented multiple
parameters, only the first one would be shown in an IDE. The
corresponding predicate in `Print.qll` documented only its first
parameter, perhaps because of an autoformatting accident earlier in
time. I've attempted to reconstruct documentation for its other
parameters based on its sibling in `Scanf.qll`.
diff --git a/cpp/ql/src/semmle/code/cpp/commons/Printf.qll b/cpp/ql/src/semmle/code/cpp/commons/Printf.qll
@@ -296,9 +296,15 @@ class FormatLiteral extends Literal {
   }
 
   /**
-   * Holds if the arguments are a parsing of a conversion specifier to this format string.
+   * Holds if the arguments are a parsing of a conversion specifier to this
+   * format string, where `n` is which conversion specifier to parse, `spec` is
+   * the whole conversion specifier, `params` is the argument to be converted
+   * in case it's not positional, `flags` contains additional format flags,
+   * `width` is the maximum width option of this input, `len` is the length
+   * flag of this input, and `conv` is the conversion character of this input.
    *
-   * @param n which conversion specifier to parse
+   * Each parameter is the empty string if no value is given by the conversion
+   * specifier.
    */
   predicate parseConvSpec(
     int n, string spec, string params, string flags, string width, string prec, string len,
diff --git a/cpp/ql/src/semmle/code/cpp/commons/Scanf.qll b/cpp/ql/src/semmle/code/cpp/commons/Scanf.qll
@@ -227,12 +227,14 @@ class ScanfFormatLiteral extends Expr {
   }
 
   /**
-   * Holds if the arguments are a parsing of a conversion specifier to this format string.
-   *  @param n     which conversion specifier to parse
-   *  @param spec  the whole conversion specifier
-   *  @param width the maximum width option of this input (empty string if none is given)
-   *  @param len   the length flag of this input (empty string if none is given)
-   *  @param conv  the conversion character of this input
+   * Holds if the arguments are a parsing of a conversion specifier to this
+   * format string, where `n` is which conversion specifier to parse, `spec` is
+   * the whole conversion specifier, `width` is the maximum width option of
+   * this input, `len` is the length flag of this input, and `conv` is the
+   * conversion character of this input.
+   *
+   * Each parameter is the empty string if no value is given by the conversion
+   * specifier.
    */
   predicate parseConvSpec(int n, string spec, string width, string len, string conv) {
     exists(int offset, string fmt, string rst, string regexp |
diff --git a/cpp/ql/src/semmle/code/cpp/security/TaintTracking.qll b/cpp/ql/src/semmle/code/cpp/security/TaintTracking.qll
@@ -376,7 +376,7 @@ predicate tainted(Expr source, Element tainted) {
  * This version gives the same results as tainted but also includes
  * data flow through global variables.
  *
- * @param globalVar the name of the last global variable used to move the
+ * The parameter `globalVar` is the name of the last global variable used to move the
  * value from source to tainted.
  */
 predicate taintedIncludingGlobalVars(Expr source, Element tainted, string globalVar) {

Original file line number	Diff line number	Diff line change
`@@ -376,7 +376,7 @@ predicate tainted(Expr source, Element tainted) {`
`376`	`376`	`* This version gives the same results as tainted but also includes`
`377`	`377`	`* data flow through global variables.`
`378`	`378`	`*`
`379`		`- * @param globalVar the name of the last global variable used to move the`
	`379`	+ * The parameter `globalVar` is the name of the last global variable used to move the
`380`	`380`	`* value from source to tainted.`
`381`	`381`	`*/`
`382`	`382`	`predicate taintedIncludingGlobalVars(Expr source, Element tainted, string globalVar) {`