From ce98353d2267558ab05574d2e2c4e2f773e973c8 Mon Sep 17 00:00:00 2001 From: Dave Bartolomeo Date: Tue, 2 Apr 2024 15:15:11 -0400 Subject: [PATCH 1/3] Allow `@param` tags to apply to record parameters --- .../Advisory/Documentation/SpuriousJavadocParam.ql | 12 ++++++++++++ .../src/change-notes/2024-04-02-javadoc-records.md | 5 +++++ .../test/query-tests/SpuriousJavadocParam/Test.java | 13 +++++++++++++ .../test/query-tests/SpuriousJavadocParam/options | 1 + .../query-tests/SpuriousJavadocParam/test.expected | 2 ++ 5 files changed, 33 insertions(+) create mode 100644 java/ql/src/change-notes/2024-04-02-javadoc-records.md create mode 100644 java/ql/test/query-tests/SpuriousJavadocParam/options diff --git a/java/ql/src/Advisory/Documentation/SpuriousJavadocParam.ql b/java/ql/src/Advisory/Documentation/SpuriousJavadocParam.ql index 691811687a79..43afd978f014 100644 --- a/java/ql/src/Advisory/Documentation/SpuriousJavadocParam.ql +++ b/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." diff --git a/java/ql/src/change-notes/2024-04-02-javadoc-records.md b/java/ql/src/change-notes/2024-04-02-javadoc-records.md new file mode 100644 index 000000000000..e3859c9618bf --- /dev/null +++ b/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. diff --git a/java/ql/test/query-tests/SpuriousJavadocParam/Test.java b/java/ql/test/query-tests/SpuriousJavadocParam/Test.java index 84e05540c051..de108008ee83 100644 --- a/java/ql/test/query-tests/SpuriousJavadocParam/Test.java +++ b/java/ql/test/query-tests/SpuriousJavadocParam/Test.java @@ -120,5 +120,18 @@ class GenericClass {} */ interface GenericInterface {} + /** + * @param i exists + * @param k does not + */ + static record SomeRecord(int i, int j) {} + + /** + * @param exists + * @param i exists + * @param k does not + */ + static record GenericRecord(int i, int j) {} + // Diagnostic Matches: Incomplete inheritance relation for type java.lang.Object and supertype none } diff --git a/java/ql/test/query-tests/SpuriousJavadocParam/options b/java/ql/test/query-tests/SpuriousJavadocParam/options new file mode 100644 index 000000000000..fc57fe025b9a --- /dev/null +++ b/java/ql/test/query-tests/SpuriousJavadocParam/options @@ -0,0 +1 @@ +//semmle-extractor-options: --javac-args -source 16 -target 16 diff --git a/java/ql/test/query-tests/SpuriousJavadocParam/test.expected b/java/ql/test/query-tests/SpuriousJavadocParam/test.expected index 42bdb93e60c7..0ade1a7d5196 100644 --- a/java/ql/test/query-tests/SpuriousJavadocParam/test.expected +++ b/java/ql/test/query-tests/SpuriousJavadocParam/test.expected @@ -12,3 +12,5 @@ | Test.java:112:6:112:12 | @param | @param tag "" 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 "" 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:132:6:132:12 | @param | @param tag "k" does not match any actual type parameter or record parameter of record "GenericRecord". | From 2336e1462749386aa3db178df112d81c2f569e09 Mon Sep 17 00:00:00 2001 From: Dave Bartolomeo Date: Thu, 4 Apr 2024 10:31:05 -0400 Subject: [PATCH 2/3] Remove expectation of spurious diagnostic --- java/ql/test/query-tests/SpuriousJavadocParam/Test.java | 2 -- 1 file changed, 2 deletions(-) diff --git a/java/ql/test/query-tests/SpuriousJavadocParam/Test.java b/java/ql/test/query-tests/SpuriousJavadocParam/Test.java index de108008ee83..434353f4c676 100644 --- a/java/ql/test/query-tests/SpuriousJavadocParam/Test.java +++ b/java/ql/test/query-tests/SpuriousJavadocParam/Test.java @@ -132,6 +132,4 @@ static record SomeRecord(int i, int j) {} * @param k does not */ static record GenericRecord(int i, int j) {} - - // Diagnostic Matches: Incomplete inheritance relation for type java.lang.Object and supertype none } From b9cfeaf6140617109572152b84ab84fbf4be067e Mon Sep 17 00:00:00 2001 From: Dave Bartolomeo Date: Tue, 9 Apr 2024 12:41:32 -0400 Subject: [PATCH 3/3] Add test case --- java/ql/test/query-tests/SpuriousJavadocParam/Test.java | 1 + java/ql/test/query-tests/SpuriousJavadocParam/test.expected | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/java/ql/test/query-tests/SpuriousJavadocParam/Test.java b/java/ql/test/query-tests/SpuriousJavadocParam/Test.java index 434353f4c676..d8891afb7564 100644 --- a/java/ql/test/query-tests/SpuriousJavadocParam/Test.java +++ b/java/ql/test/query-tests/SpuriousJavadocParam/Test.java @@ -128,6 +128,7 @@ static record SomeRecord(int i, int j) {} /** * @param exists + * @param does not * @param i exists * @param k does not */ diff --git a/java/ql/test/query-tests/SpuriousJavadocParam/test.expected b/java/ql/test/query-tests/SpuriousJavadocParam/test.expected index 0ade1a7d5196..f184473ea4a9 100644 --- a/java/ql/test/query-tests/SpuriousJavadocParam/test.expected +++ b/java/ql/test/query-tests/SpuriousJavadocParam/test.expected @@ -13,4 +13,5 @@ | 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 "" 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:132:6:132:12 | @param | @param tag "k" does not match any actual type parameter or record parameter of record "GenericRecord". | +| Test.java:131:6:131:12 | @param | @param tag "" 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". |