Merge pull request #6645 from Marcono1234/marcono1234/spurious-javadoc-param-generic-class

Java: Detect spurious param Javadoc tag of generic classes

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

@@ -39,6 +39,12 @@ public void html(int ordinate){ ... }
  */ 
 public <T> void parameterized(T parameter){ ... }
 
+/**
+ * BAD: The following param tag refers to a non-existent type parameter.
+ * 
+ * @param <X> The type of the elements.
+ */
+class Generic<T> { ...}
 
 /**
  * GOOD: A proper Javadoc comment.

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

@@ -6,15 +6,15 @@
 
 <overview>
 <p>
-Javadoc comments for public methods and constructors should use the <code>@param</code> tag to describe the available
-parameters. If the comment includes any empty, incorrect or outdated parameter names then this will make 
+Javadoc comments for public methods, constructors and generic classes should use the <code>@param</code> tag to describe the available
+parameters and type parameters. If the comment includes any empty, incorrect or outdated parameter names then this will make 
 the documentation more difficult to read.
 </p>
 
 </overview>
 <recommendation>
 
-<p>The Javadoc comment for a method or constructor should always use non-empty <code>@param</code> values that match actual parameter or type parameter names.</p>
+<p>The Javadoc comment for a method, constructor or generic class should always use non-empty <code>@param</code> values that match actual parameter or type parameter names.</p>
 
 </recommendation>
 <example>

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

@@ -1,6 +1,7 @@
 /**
  * @name Spurious Javadoc @param tags
- * @description Javadoc @param tags that do not match any parameters in the method or constructor are confusing.
+ * @description Javadoc @param tags that do not match any parameters in the method or constructor or
+ *              any type parameters of the annotated class are confusing.
  * @kind problem
  * @problem.severity recommendation
  * @precision very-high
@@ -10,21 +11,33 @@
 
 import java
 
-from Callable callable, ParamTag paramTag, string what, string msg
+from Documentable documentable, ParamTag paramTag, string msg
 where
-  callable.(Documentable).getJavadoc().getAChild() = paramTag and
-  (if callable instanceof Constructor then what = "constructor" else what = "method") and
+  documentable.getJavadoc().getAChild() = paramTag and
   if exists(paramTag.getParamName())
   then
-    // The tag's value is neither matched by a callable parameter name ...
-    not callable.getAParameter().getName() = paramTag.getParamName() and
-    // ... nor by a type parameter name.
-    not exists(TypeVariable tv | tv.getGenericCallable() = callable |
+    documentable instanceof Callable and
+    exists(string what |
+      if documentable instanceof Constructor then what = "constructor" else what = "method"
+    |
+      // The tag's value is neither matched by a callable parameter name ...
+      not documentable.(Callable).getAParameter().getName() = paramTag.getParamName() and
+      // ... nor by a type parameter name.
+      not exists(TypeVariable tv | tv.getGenericCallable() = documentable |
+        "<" + tv.getName() + ">" = paramTag.getParamName()
+      ) and
+      msg =
+        "@param tag \"" + paramTag.getParamName() + "\" does not match any actual parameter of " +
+          what + " \"" + documentable.getName() + "()\"."
+    )
+    or
+    documentable instanceof ClassOrInterface and
+    not exists(TypeVariable tv | tv.getGenericType() = documentable |
       "<" + tv.getName() + ">" = paramTag.getParamName()
     ) and
     msg =
-      "@param tag \"" + paramTag.getParamName() + "\" does not match any actual parameter of " +
-        what + " \"" + callable.getName() + "()\"."
+      "@param tag \"" + paramTag.getParamName() +
+        "\" does not match any actual type parameter of type \"" + documentable.getName() + "\"."
   else
     // The tag has no value at all.
     msg = "This @param tag does not have a value."