QL: detect toplevel block-comments that should be QLDoc

Author: erik-krogh

ql/ql/src/queries/style/NonDocBlock.ql

@@ -30,23 +30,43 @@ int getLineAboveNodeThatCouldHaveDoc(File file) {
 pragma[noinline]
 BlockComment getACommentThatCouldBeQLDoc(File file) {
   file = result.getLocation().getFile() and
-  result.getLocation().getEndLine() = getLineAboveNodeThatCouldHaveDoc(file) and
   result.getLocation().getFile().getExtension() = "qll" and
-  not result.getContents().matches("/**%")
+  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
+  )
 }
 
 pragma[noinline]
-BlockComment getCommentAt(File file, int endLine) {
+BlockComment getCommentAtEnd(File file, int endLine) {
   result = getACommentThatCouldBeQLDoc(file) and
   result.getLocation().getEndLine() = endLine
 }
 
-from AstNode node, BlockComment comment
+pragma[noinline]
+BlockComment getCommentAtStart(File file, int startLine) {
+  result = getACommentThatCouldBeQLDoc(file) and
+  result.getLocation().getStartLine() = startLine
+}
+
+from AstNode node, BlockComment comment, string nodeDescrip
 where
-  canHaveQLDoc(node) and
+  (
+    canHaveQLDoc(node) and
+    comment = getCommentAtEnd(node.getLocation().getFile(), node.getLocation().getStartLine() - 1) and
+    nodeDescrip = "the below code"
+    or
+    node instanceof TopLevel and
+    comment = getCommentAtStart(node.getLocation().getFile(), 1) and
+    nodeDescrip = "the file"
+  ) and
   not exists(node.getQLDoc()) and
   not node.(ClassPredicate).isOverride() and // ignore override predicates
   not node.hasAnnotation("deprecated") and // ignore deprecated
-  not node.hasAnnotation("private") and // ignore private
-  comment = getCommentAt(node.getLocation().getFile(), node.getLocation().getStartLine() - 1)
-select comment, "Block comment could be QLDoc for $@.", node, "the below code"
+  not node.hasAnnotation("private") // ignore private
+select comment, "Block comment could be QLDoc for $@.", node, nodeDescrip