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

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`.
This commit is contained in:
Jonas Jensen
2019-09-05 11:01:19 +02:00
parent 8524b95baa
commit 64e2277904
3 changed files with 17 additions and 9 deletions

View File

@@ -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,

View File

@@ -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 |

View File

@@ -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) {