Merge pull request #16103 from github/dbartol/javadoc-record

Allow `@param` tags to apply to record parameters

Author: Dave Bartolomeo

java/ql/src/Advisory/Documentation/SpuriousJavadocParam.ql

@@ -32,12 +32,24 @@ where
     )
     or
     documentable instanceof ClassOrInterface and
+    not documentable instanceof Record and
     not exists(TypeVariable tv | tv.getGenericType() = documentable |
       "<" + tv.getName() + ">" = paramTag.getParamName()
     ) and
     msg =
       "@param tag \"" + paramTag.getParamName() +
         "\" does not match any actual type parameter of type \"" + documentable.getName() + "\"."
+    or
+    documentable instanceof Record and
+    not exists(TypeVariable tv | tv.getGenericType() = documentable |
+      "<" + tv.getName() + ">" = paramTag.getParamName()
+    ) and
+    not documentable.(Record).getCanonicalConstructor().getAParameter().getName() =
+      paramTag.getParamName() and
+    msg =
+      "@param tag \"" + paramTag.getParamName() +
+        "\" does not match any actual type parameter or record parameter of record \"" +
+        documentable.getName() + "\"."
   else
     // The tag has no value at all.
     msg = "This @param tag does not have a value."

java/ql/src/change-notes/2024-04-02-javadoc-records.md

@@ -0,0 +1,5 @@
+---
+category: minorAnalysis
+---
+* The `java/unknown-javadoc-parameter` now accepts `@param` tags that apply to the parameters of a
+  record.

java/ql/test/query-tests/SpuriousJavadocParam/Test.java

@@ -120,5 +120,17 @@ class GenericClass<T> {}
    */
   interface GenericInterface<T> {}
 
-  // Diagnostic Matches: Incomplete inheritance relation for type java.lang.Object and supertype none
+  /**
+   * @param i exists
+   * @param k does not
+   */
+  static record SomeRecord(int i, int j) {}
+
+  /**
+   * @param <T> exists
+   * @param <U> does not
+   * @param i exists
+   * @param k does not
+   */
+  static record GenericRecord<T>(int i, int j) {}
 }

java/ql/test/query-tests/SpuriousJavadocParam/options

@@ -0,0 +1 @@
+//semmle-extractor-options: --javac-args -source 16 -target 16

java/ql/test/query-tests/SpuriousJavadocParam/test.expected

@@ -12,3 +12,6 @@
 | Test.java:112:6:112:12 | @param | @param tag "<X>" does not match any actual type parameter of type "GenericClass". |
 | Test.java:118:6:118:12 | @param | @param tag "T" does not match any actual type parameter of type "GenericInterface". |
 | Test.java:119:6:119:12 | @param | @param tag "<X>" does not match any actual type parameter of type "GenericInterface". |
+| Test.java:125:6:125:12 | @param | @param tag "k" does not match any actual type parameter or record parameter of record "SomeRecord". |
+| Test.java:131:6:131:12 | @param | @param tag "<U>" does not match any actual type parameter or record parameter of record "GenericRecord". |
+| Test.java:133:6:133:12 | @param | @param tag "k" does not match any actual type parameter or record parameter of record "GenericRecord". |