QL: don't flag up comments placed on the same line as non-comments

erik-krogh · erik-krogh · commit 78c9fb3d76b0 · 2022-11-16T13:36:28.000+01:00
diff --git a/ql/ql/src/queries/style/NonDocBlock.ql b/ql/ql/src/queries/style/NonDocBlock.ql
@@ -29,16 +29,31 @@ int getLineAboveNodeThatCouldHaveDoc(File file) {
 
 pragma[noinline]
 BlockComment getACommentThatCouldBeQLDoc(File file) {
-  file = result.getLocation().getFile() and
-  result.getLocation().getFile().getExtension() = "qll" and
-  not result.getContents().matches("/**%") and
-  (
-    // above something that can be commented.
-    result.getLocation().getEndLine() = getLineAboveNodeThatCouldHaveDoc(file)
-    or
-    // toplevel in file.
-    result.getLocation().getStartLine() = 1 and
-    result.getLocation().getStartColumn() = 1
+  exists(Location loc | loc = result.getLocation() |
+    file = loc.getFile() and
+    loc.getFile().getExtension() = "qll" and
+    not result.getContents().matches("/**%") and
+    not [loc.getStartLine(), loc.getEndLine()] = getLinesWithNonComment(file) and
+    (
+      // above something that can be commented.
+      loc.getEndLine() = getLineAboveNodeThatCouldHaveDoc(file)
+      or
+      // toplevel in file.
+      loc.getStartLine() = 1 and
+      loc.getStartColumn() = 1
+    )
+  )
+}
+
+pragma[noinline]
+int getLinesWithNonComment(File f) {
+  exists(AstNode n, Location loc |
+    not n instanceof Comment and
+    not n instanceof TopLevel and
+    loc = n.getLocation() and
+    loc.getFile() = f
+  |
+    result = [loc.getEndLine(), loc.getStartLine()]
   )
 }
 
diff --git a/ql/ql/test/queries/style/NonDocBlock/Foo.qll b/ql/ql/test/queries/style/NonDocBlock/Foo.qll
@@ -11,3 +11,12 @@ predicate foo() { any() }
 class Foo extends string {
   Foo() { this = "FOo" }
 }
+
+/**
+ * This is also fine.
+ */
+/*abstract*/ class Bar extends string {
+  string getMergeRaw() { none() } // <- fine. The abstract comment is fine, it doesn't need to be QLDoc.
+
+  Bar() { this = "bar" }
+}
diff --git a/ql/ql/test/queries/style/NonDocBlock/NonDocBlock.expected b/ql/ql/test/queries/style/NonDocBlock/NonDocBlock.expected
@@ -1,2 +1,2 @@
-| Foo.qll:1:1:3:3 | BlockComment | Block comment could be QLDoc for $@. | Foo.qll:1:1:13:2 | TopLevel | the file |
+| Foo.qll:1:1:3:3 | BlockComment | Block comment could be QLDoc for $@. | Foo.qll:1:1:22:2 | TopLevel | the file |
 | Foo.qll:10:1:10:24 | BlockComment | Block comment could be QLDoc for $@. | Foo.qll:11:7:11:9 | Class Foo | the below code |

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`		`-\| Foo.qll:1:1:3:3 \| BlockComment \| Block comment could be QLDoc for $@. \| Foo.qll:1:1:13:2 \| TopLevel \| the file \|`
	`1`	`+\| Foo.qll:1:1:3:3 \| BlockComment \| Block comment could be QLDoc for $@. \| Foo.qll:1:1:22:2 \| TopLevel \| the file \|`
`2`	`2`	`\| Foo.qll:10:1:10:24 \| BlockComment \| Block comment could be QLDoc for $@. \| Foo.qll:11:7:11:9 \| Class Foo \| the below code \|`