Java: handle printing an empty comment (/**/); add relevant tests

Author: smowton

java/ql/lib/change-notes/2022-12-15-empty-multiline-comments.md

@@ -0,0 +1,4 @@
+---
+category: fix
+---
+* We now correctly handle empty block comments, like `/**/`. Previously these could be mistaken for Javadoc comments and led to attribution of Javadoc tags to the wrong declaration.

java/ql/lib/semmle/code/java/Javadoc.qll

@@ -33,7 +33,11 @@ class Javadoc extends JavadocParent, @javadoc {
   string getAuthor() { result = this.getATag("@author").getChild(0).toString() }
 
   override string toString() {
-    result = this.toStringPrefix() + this.getChild(0) + this.toStringPostfix()
+    exists(string childStr |
+      if exists(this.getChild(0)) then childStr = this.getChild(0).toString() else childStr = ""
+    |
+      result = this.toStringPrefix() + childStr + this.toStringPostfix()
+    )
   }
 
   private string toStringPrefix() {
@@ -48,7 +52,7 @@ class Javadoc extends JavadocParent, @javadoc {
     if isEolComment(this)
     then result = ""
     else (
-      if strictcount(this.getAChild()) = 1 then result = " */" else result = " ... */"
+      if strictcount(this.getAChild()) > 1 then result = " ... */" else result = " */"
     )
   }
 

java/ql/test/library-tests/comments/PrintAst.expected

@@ -14,6 +14,18 @@ Test.java:
 #   21|     3: [Method] test
 #   21|       3: [TypeAccess] void
 #   21|       5: [BlockStmt] { ... }
+#   23|     4: [Method] method1
+#   23|       3: [TypeAccess] void
+#   23|       5: [BlockStmt] { ... }
+#   24|     5: [Method] method2
+#   24|       3: [TypeAccess] void
+#   24|       5: [BlockStmt] { ... }
+#   28|     6: [Method] method3
+#-----|       0: (Javadoc)
+#   25|         1: [Javadoc] /** JavaDoc for method3 */
+#   26|           0: [JavadocText] JavaDoc for method3
+#   28|       3: [TypeAccess] void
+#   28|       5: [BlockStmt] { ... }
 TestWindows.java:
 #    0| [CompilationUnit] TestWindows
 #    5|   1: [Class] TestWindows

java/ql/test/library-tests/comments/Test.java

@@ -19,4 +19,11 @@ void m() {
 	// an end-of-line comment with trailing whitespace        
 	//an end-of-line comment without a leading space
 	void test() {} // an end-of-line comment with preceding code
+
+        void method1() { /**/ } // A block comment containing the /** JavaDoc prefix }
+        void method2() { }
+        /**
+         * JavaDoc for method3
+         */
+        void method3() { }
 }

java/ql/test/library-tests/comments/toString.expected

@@ -8,6 +8,9 @@
 | Test.java:19:2:19:59 | // an end-of-line comment with trailing whitespace         |
 | Test.java:20:2:20:49 | //an end-of-line comment without a leading space |
 | Test.java:21:17:21:61 | // an end-of-line comment with preceding code |
+| Test.java:23:26:23:29 | /*  */ |
+| Test.java:23:33:23:86 | // A block comment containing the /** JavaDoc prefix } |
+| Test.java:25:9:27:11 | /** JavaDoc for method3 */ |
 | TestWindows.java:1:1:4:3 | /** A JavaDoc comment ... */ |
 | TestWindows.java:6:2:6:45 | /** A JavaDoc comment with a single line. */ |
 | TestWindows.java:8:3:8:27 | // a single-line comment |