CPP: Move comments explaining implementation details into the body of 'looksLikeCode'.

Author: geoffw0

cpp/ql/src/Documentation/CommentedOutCode.qll

@@ -2,24 +2,17 @@ import cpp
 
 /**
  * Holds if `line` looks like a line of code.
- * Matches comment lines ending with '{', '}' or ';' that do not start with '>' or contain '@{' or '@}', but first filters out:
- *  * HTML entities in common notation (e.g. > and é)
- *  * HTML entities in decimal notation (e.g. à)
- *  * HTML entities in hexadecimal notation (e.g. 灟)
- * To account for the code generated by protobuf, we also insist that the comment
- * does not begin with `optional` or `repeated` and end with a `;`, which would
- * normally be a quoted bit of literal `.proto` specification above the associated
- * declaration.
- * To account for emacs folding markers, we ignore any line containing
- * `{{{` or `}}}`.
- *
- * Finally, some code tends to embed GUIDs in comments, so we also exclude those.
  */
 bindingset[line]
 private predicate looksLikeCode(string line) {
   exists(string trimmed |
+    // trim leading and trailing whitespace, and HTML codes: 
+    //  * HTML entities in common notation (e.g. > and é)
+    //  * HTML entities in decimal notation (e.g. à)
+    //  * HTML entities in hexadecimal notation (e.g. 灟)
     trimmed = line.regexpReplaceAll("(?i)(^\\s+|&#?[a-z0-9]{1,31};|\\s+$)", "")
   |
+    // Match comment lines ending with '{', '}' or ';'
     trimmed.regexpMatch(".*[{};]") and
     (
       // If this line looks like code because it ends with a closing
@@ -32,9 +25,18 @@ private predicate looksLikeCode(string line) {
       // benign use of braces such as a JSON example or explanatory
       // pseudocode.
       trimmed.regexpMatch(".*(\\)|const|volatile|override|final|noexcept|&)\\s*\\{.*")
-    ) and
-    not trimmed
+    ) and (
+      // Exclude lines that start with '>' or contain '@{' or '@}'.
+      // To account for the code generated by protobuf, we also insist that the comment
+      // does not begin with `optional` or `repeated` and end with a `;`, which would
+      // normally be a quoted bit of literal `.proto` specification above the associated
+      // declaration.
+      // To account for emacs folding markers, we ignore any line containing
+      // `{{{` or `}}}`.
+      // Finally, some code tends to embed GUIDs in comments, so we also exclude those.
+      not trimmed
         .regexpMatch("(>.*|.*[\\\\@][{}].*|(optional|repeated) .*;|.*(\\{\\{\\{|\\}\\}\\}).*|\\{[-0-9a-zA-Z]+\\})")
+    )
   )
 }