C++: Turn more "short" comments into "long"

jbj · jbj · commit 8e98d4250405 · 2019-09-09T11:04:04.000+02:00
The autoformatter is opinionated about comment styles and assumes that
"short" comments attach to the following item while "long" comments are
items themselves. I found top-level short comments with the following
two commands and then searched the output for empty lines that came
after the comment.

    git grep -A1 '^/\* .*\*/' cpp/ql/src
    git grep -A1 '^//' 'cpp/ql/src/**/*.ql*'
diff --git a/cpp/ql/src/Likely Bugs/OO/NonVirtualDestructorInBaseClass.ql b/cpp/ql/src/Likely Bugs/OO/NonVirtualDestructorInBaseClass.ql
@@ -11,8 +11,10 @@
  */
 import cpp
 
-// find classes with virtual functions that have a destructor that is not virtual and for which there exists a derived class
-// when calling the destructor of a derived class the destructor in the base class may not be called
+/*
+ * Find classes with virtual functions that have a destructor that is not virtual and for which there exists a derived class
+ * when calling the destructor of a derived class the destructor in the base class may not be called
+ */
 
 from Class c
 where exists(VirtualFunction f | f.getDeclaringType() = c)
diff --git a/cpp/ql/src/jsf/4.09 Style/AV Rule 45.ql b/cpp/ql/src/jsf/4.09 Style/AV Rule 45.ql
@@ -10,8 +10,10 @@
  */
 import cpp
 
-// INTERPRETATION: just check for the absence of camel-case, ie
-// forbid 'aB' in identifier names
+/*
+ * INTERPRETATION: just check for the absence of camel-case, ie
+ * forbid 'aB' in identifier names
+ */
 
 from Declaration d, string name, string lowerCase, string upperCase, int pos
 where name = d.getName() and
diff --git a/cpp/ql/src/jsf/4.09 Style/AV Rule 53.ql b/cpp/ql/src/jsf/4.09 Style/AV Rule 53.ql
@@ -10,7 +10,10 @@
  */
 import cpp
 
-// Interpretation: use .h, never .H, .hpp or other variants. What else could be meant by 'header file'?
+/*
+ * Interpretation: use .h, never .H, .hpp or other variants. What else could be
+ * meant by 'header file'?
+ */
 
 from File f
 where (f.getExtension().toLowerCase() = "h" or f.getExtension().toLowerCase() = "hpp")
diff --git a/cpp/ql/src/jsf/4.10 Classes/AV Rule 78.ql b/cpp/ql/src/jsf/4.10 Classes/AV Rule 78.ql
@@ -11,8 +11,10 @@
  */
 import cpp
 
-// find classes with virtual functions that have a destructor that is not virtual and for which there exists a derived class
-// when calling the destructor of a derived class the destructor in the base class may not be called
+/*
+ * Find classes with virtual functions that have a destructor that is not virtual and for which there exists a derived class
+ * when calling the destructor of a derived class the destructor in the base class may not be called
+ */
 
 from Class c
 where exists(VirtualFunction f | f.getDeclaringType() = c)
diff --git a/cpp/ql/src/jsf/4.10 Classes/AV Rule 82.ql b/cpp/ql/src/jsf/4.10 Classes/AV Rule 82.ql
@@ -12,6 +12,10 @@
  */
 import cpp
 
+/*
+ * Applies to all assignment operators, not just the copy assignment operator.
+ */
+
 predicate callOnThis(FunctionCall fc) {
   // `this->f(...)`
   fc.getQualifier() instanceof ThisExpr or
@@ -88,8 +92,6 @@ predicate assignOperatorWithWrongResult(Operator op, string msg) {
   and msg = "Assignment operator in class " + op.getDeclaringType().getName() + " does not return a reference to *this."
 }
 
-// Applies to all assignment operators, not just a copy assignment operator
-
 from Operator op, string msg
 where assignOperatorWithWrongType(op, msg)
   or assignOperatorWithWrongResult(op, msg)
diff --git a/cpp/ql/src/jsf/4.15 Declarations and Definitions/AV Rule 138.ql b/cpp/ql/src/jsf/4.15 Declarations and Definitions/AV Rule 138.ql
@@ -22,9 +22,11 @@ import cpp
  * NOTE: only applies to C++; rules for C are different.
  */
 
-// FOR FUTURE REFERENCE ONLY - CURRENTLY USELESS BECAUSE OF POPULATOR LIMITATIONS
-// We need to have all the declarations of a variable to make this work; the extractor
-// does not currently provide that.
+/*
+ * FOR FUTURE REFERENCE ONLY - CURRENTLY USELESS BECAUSE OF POPULATOR LIMITATIONS
+ * We need to have all the declarations of a variable to make this work; the extractor
+ * does not currently provide that.
+ */
 
 predicate externalLinkage(Variable v) {
      v.getADeclarationEntry().hasSpecifier("extern")
diff --git a/cpp/ql/src/jsf/4.18 Constants/AV Rule 151.1.ql b/cpp/ql/src/jsf/4.18 Constants/AV Rule 151.1.ql
@@ -9,12 +9,15 @@
  */
 import cpp
 
-// Interpretation (from the example in AV151.1):
-//   rather than doing points-to to find writes into string literals, the
-//   check forbids assigning to non-const string variables, which prevents it.
-// Casting the const-ness of the variable away is still possible; ideally it
-// should be prevented but it doesn't seem worth the effort since it will likely
-// flag another rule.
+/*
+ * Interpretation (from the example in AV151.1):
+ *   rather than doing points-to to find writes into string literals, the
+ *   check forbids assigning to non-const string variables, which prevents it.
+ *
+ * Casting the const-ness of the variable away is still possible; ideally it
+ * should be prevented but it doesn't seem worth the effort since it will likely
+ * flag another rule.
+ */
 
 class NonConstStringType extends DerivedType {
   NonConstStringType() {
diff --git a/cpp/ql/src/jsf/4.20 Unions and Bit Fields/AV Rule 153.ql b/cpp/ql/src/jsf/4.20 Unions and Bit Fields/AV Rule 153.ql
@@ -9,7 +9,9 @@
  */
 import cpp
 
-// see MISRA Rule 9-5-1
+/*
+ * See MISRA Rule 9-5-1
+ */
 
 from Union u
 where u.fromSource()
diff --git a/cpp/ql/src/jsf/4.20 Unions and Bit Fields/AV Rule 156.ql b/cpp/ql/src/jsf/4.20 Unions and Bit Fields/AV Rule 156.ql
@@ -11,9 +11,11 @@
  */
 import cpp
 
-// TODO: what about the "shall only be accessed" part?
-// TODO: implement better check for namelessness (at the moment we rely on the fact
-//       that the frontend creates dummy names of the form "(unnamed X)" for nameless members)
+/*
+ * TODO: what about the "shall only be accessed" part?
+ * TODO: implement better check for namelessness (at the moment we rely on the fact
+ *       that the frontend creates dummy names of the form "(unnamed X)" for nameless members)
+ */
 
 from Declaration m
 where m.isMember() and m.getName().matches("(%") and
diff --git a/cpp/ql/src/jsf/4.21 Operators/AV Rule 157.ql b/cpp/ql/src/jsf/4.21 Operators/AV Rule 157.ql
@@ -11,7 +11,9 @@
  */
 import cpp
 
-// see MISRA Rule 5-14-1
+/*
+ * See MISRA Rule 5-14-1
+ */
 
 from BinaryLogicalOperation blo
 where blo.fromSource() and
diff --git a/cpp/ql/src/jsf/4.21 Operators/AV Rule 158.ql b/cpp/ql/src/jsf/4.21 Operators/AV Rule 158.ql
@@ -11,7 +11,9 @@
  */
 import cpp
 
-// NB: we only check if the immediate operands are (unparenthesised) binary operations
+/*
+ * NB: we only check if the immediate operands are (unparenthesised) binary operations
+ */
 
 from BinaryLogicalOperation blo, BinaryOperation bo
 where blo.fromSource() and
diff --git a/cpp/ql/src/jsf/4.21 Operators/AV Rule 159.ql b/cpp/ql/src/jsf/4.21 Operators/AV Rule 159.ql
@@ -7,8 +7,11 @@
  * @tags correctness
  *       external/jsf
  */
-// See More Effective C++ item 7
-// Note: Meyers allows unary & to be overloaded but not comma
+
+/*
+ * See More Effective C++ item 7.
+ * Note: Meyers allows unary & to be overloaded but not comma
+ */
 
 import cpp
 
diff --git a/cpp/ql/src/jsf/4.21 Operators/AV Rule 165.ql b/cpp/ql/src/jsf/4.21 Operators/AV Rule 165.ql
@@ -11,7 +11,9 @@
  */
 import cpp
 
-// see MISRA Rule 5-3-2
+/*
+ * See MISRA Rule 5-3-2
+ */
 
 from UnaryMinusExpr ume
 where ume.getOperand().getExplicitlyConverted().getUnderlyingType().(IntegralType).isUnsigned()
diff --git a/cpp/ql/src/jsf/4.21 Operators/AV Rule 168.ql b/cpp/ql/src/jsf/4.21 Operators/AV Rule 168.ql
@@ -10,7 +10,9 @@
  */
 import cpp
 
-// see MISRA Rule 5-18-1
+/*
+ * See MISRA Rule 5-18-1
+ */
 
 from CommaExpr ce
 where ce.fromSource()
diff --git a/cpp/ql/src/jsf/4.22 Pointers and References/AV Rule 173.ql b/cpp/ql/src/jsf/4.22 Pointers and References/AV Rule 173.ql
@@ -11,14 +11,16 @@
  */
 import cpp
 
-// see MISRA Rule 7-5-2
-// TODO: this catches only the most obvious cases
-
-// Current caught cases: assignment x = &y (literally) where
-//   - y is a local
-//   - EITHER x is a nonlocal
-//   - OR x is a local defined in an enclosing scope
-//   - OR x has static storage duration
+/*
+ * see MISRA Rule 7-5-2
+ * TODO: this catches only the most obvious cases
+ *
+ * Current caught cases: assignment x = &y (literally) where
+ *   - y is a local
+ *   - EITHER x is a nonlocal
+ *   - OR x is a local defined in an enclosing scope
+ *   - OR x has static storage duration
+ */
 
 from Assignment a, Variable global, Variable local
 where a.fromSource() and
diff --git a/cpp/ql/src/jsf/4.25 Expressions/AV Rule 202.ql b/cpp/ql/src/jsf/4.25 Expressions/AV Rule 202.ql
@@ -9,7 +9,9 @@
  */
 import cpp
 
-// see MISRA 6-2-2
+/*
+ * See MISRA 6-2-2
+ */
 
 from EqualityOperation e
 where e.fromSource() and
diff --git a/cpp/ql/src/jsf/4.28 Portable Code/AV Rule 212.ql b/cpp/ql/src/jsf/4.28 Portable Code/AV Rule 212.ql
@@ -11,7 +11,9 @@
  */
 import cpp
 
-/* We check for the use of the "a + b < a" idiom. */
+/*
+ * This query checks for the use of the "a + b < a" idiom.
+ */
 
 predicate isNonNegative(Expr e) {
      e.getUnderlyingType().(IntegralType).isUnsigned()
diff --git a/cpp/ql/src/jsf/4.28 Portable Code/AV Rule 213.ql b/cpp/ql/src/jsf/4.28 Portable Code/AV Rule 213.ql
@@ -11,13 +11,15 @@
  */
 import cpp
 
-// Interpretation and deviations:
-//   - if the higher operator has precedence > arithmetic then it is fine
-//     RATIONALE: exprs like f(), *x, &x are easily understood to bind tightly
-//   - if the higher operator is the RHS of an assign then it is fine
-//     RATIONALE: cf. MISRA, too many cases excluded otherwise
-//   - comparison operators can be mixed with arithmetic
-//     RATIONALE: x==y+z is common and unambiguous
+/*
+ * Interpretation and deviations:
+ *   - if the higher operator has precedence > arithmetic then it is fine
+ *     RATIONALE: exprs like f(), *x, &x are easily understood to bind tightly
+ *   - if the higher operator is the RHS of an assign then it is fine
+ *     RATIONALE: cf. MISRA, too many cases excluded otherwise
+ *   - comparison operators can be mixed with arithmetic
+ *     RATIONALE: x==y+z is common and unambiguous
+ */
 
 predicate arithmeticPrecedence(int p) { p = 12 or p = 13  }
 predicate comparisonPrecedence(int p) { p = 9 or p = 10 }
diff --git a/cpp/ql/src/semmle/code/cpp/commons/Assertions.qll b/cpp/ql/src/semmle/code/cpp/commons/Assertions.qll
@@ -70,4 +70,6 @@ class RecoverableAssert extends MacroInvocation, Assertion {
   }
 }
 
-/* More assertion definitions go here. */
+/*
+ * More assertion definitions go here.
+ */
diff --git a/cpp/ql/src/semmle/code/cpp/controlflow/Guards.qll b/cpp/ql/src/semmle/code/cpp/controlflow/Guards.qll
@@ -109,11 +109,11 @@ private predicate is_condition(Expr guard) {
 }
 
 
- /* Simplify conditions in the source to the canonical form l op r + k.
+/*
+ * Simplification of equality expressions:
+ * Simplify conditions in the source to the canonical form l op r + k.
  */
 
-/* Simplification of equality expressions */
-
 /**
  * Holds if `left == right + k` is `areEqual` given that test is `testIsTrue`.
  *
@@ -196,7 +196,8 @@ private predicate add_eq(ComparisonOperation cmp, Expr left, Expr right, int k,
     )
 }
 
-/* Simplification of inequality expressions
+/*
+ * Simplification of inequality expressions:
  * Simplify conditions in the source to the canonical form l < r + k.
  */
 
diff --git a/cpp/ql/src/semmle/code/cpp/security/CommandExecution.qll b/cpp/ql/src/semmle/code/cpp/security/CommandExecution.qll
@@ -1,4 +1,4 @@
-/* Definitions related to execution of commands */
+/** Provides definitions related to execution of commands */
 
 import cpp
 
diff --git a/cpp/ql/src/semmle/code/cpp/security/Overflow.qll b/cpp/ql/src/semmle/code/cpp/security/Overflow.qll
@@ -1,7 +1,9 @@
 import cpp
 import semmle.code.cpp.controlflow.Dominance
 
-/* Guarding */
+/*
+ * Guarding
+ */
 
 /** is the size of this use guarded using 'abs'? */
 predicate guardedAbs(Operation e, Expr use) {
