Issue #11736: Update doc for MissingJavadocTypeCheck

src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/MissingJavadocTypeCheck.java

@@ -53,7 +53,8 @@
  * </li>
  * <li>
  * Property {@code skipAnnotations} - specify annotations that allow missed
- * documentation. Only short names are allowed, e.g. {@code Generated}.
+ * documentation. If annotation is present in target sources in multiple forms of qualified
+ * name, all forms should be listed in this property.
  * Type is {@code java.lang.String[]}.
  * Default value is {@code Generated}.
  * </li>
@@ -126,8 +127,16 @@
  * class PackagePrivateClass {}
  * </pre>
  * <p>
- * Example that allows missing comments for classes annotated with {@code @SpringBootApplication}
- * and {@code @Configuration}:
+ * To configure a check that allows missing comments for classes annotated
+ * with {@code @SpringBootApplication} and {@code @Configuration}:
+ * </p>
+ * <pre>
+ * &lt;module name="MissingJavadocType"&gt;
+ *   &lt;property name="skipAnnotations" value="SpringBootApplication,Configuration"/&gt;
+ * &lt;/module&gt;
+ * </pre>
+ * <p>
+ * Example:
  * </p>
  * <pre>
  * &#64;SpringBootApplication // no violations about missing comment on class
@@ -137,14 +146,28 @@
  * class DatabaseConfiguration {}
  * </pre>
  * <p>
- * Use following configuration:
+ * To configure a check that allows missing comments for classes annotated with {@code @Annotation}
+ * and {@code @MyClass.Annotation}:
  * </p>
  * <pre>
  * &lt;module name="MissingJavadocType"&gt;
- *   &lt;property name="skipAnnotations" value="SpringBootApplication,Configuration"/&gt;
+ *   &lt;property name="skipAnnotations" value="Annotation,MyClass.Annotation"/&gt;
  * &lt;/module&gt;
  * </pre>
  * <p>
+ * Example:
+ * </p>
+ * <pre>
+ * &#64;Annotation // ok
+ * class Class1 {}
+ *
+ * &#64;MyClass.Annotation // ok
+ * class Class2 {}
+ *
+ * &#64;com.mycompany.MyClass.Annotation // violation, as this form is missed in config
+ * class Class3 {}
+ * </pre>
+ * <p>
  * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
  * </p>
  * <p>
@@ -174,7 +197,8 @@ public class MissingJavadocTypeCheck extends AbstractCheck {
 
     /**
      * Specify annotations that allow missed documentation.
-     * Only short names are allowed, e.g. {@code Generated}.
+     * If annotation is present in target sources in multiple forms of qualified
+     * name, all forms should be listed in this property.
      */
     private Set<String> skipAnnotations = Set.of("Generated");
 
@@ -198,7 +222,8 @@ public void setExcludeScope(Scope excludeScope) {
 
     /**
      * Setter to specify annotations that allow missed documentation.
-     * Only short names are allowed, e.g. {@code Generated}.
+     * If annotation is present in target sources in multiple forms of qualified
+     * name, all forms should be listed in this property.
      *
      * @param userAnnotations user's value.
      */

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/javadoc/MissingJavadocTypeCheck.xml

@@ -24,7 +24,8 @@
                        name="skipAnnotations"
                        type="java.lang.String[]">
                <description>specify annotations that allow missed
- documentation. Only short names are allowed, e.g. {@code Generated}.</description>
+ documentation. If annotation is present in target sources in multiple forms of qualified
+ name, all forms should be listed in this property.</description>
             </property>
             <property default-value="INTERFACE_DEF,CLASS_DEF,ENUM_DEF,ANNOTATION_DEF,RECORD_DEF"
                        name="tokens"

src/xdocs/config_javadoc.xml

@@ -2885,7 +2885,8 @@ package com.checkstyle.api; // violation
               <td>skipAnnotations</td>
               <td>
                 specify annotations that allow missed documentation.
-                Only short names are allowed, e.g. <code>Generated</code>.
+                If annotation is present in target sources in multiple forms of qualified
+                name, all forms should be listed in this property.
               </td>
               <td><a href="property_types.html#String.5B.5D">String[]</a></td>
               <td><code>Generated</code></td>
@@ -2979,23 +2980,44 @@ protected class PublicClass {}
 class PackagePrivateClass {}
         </source>
 
-        <p>
-          Example that allows missing comments for classes annotated with
+        <p>To configure a check that allows missing comments for classes annotated with
           <code>@SpringBootApplication</code> and <code>@Configuration</code>:
         </p>
         <source>
+&lt;module name="MissingJavadocType"&gt;
+  &lt;property name="skipAnnotations" value="SpringBootApplication,Configuration"/&gt;
+&lt;/module&gt;
+        </source>
+        <p>Example:</p>
+        <source>
 @SpringBootApplication // no violations about missing comment on class
 public class Application {}
 
 @Configuration // no violations about missing comment on class
 class DatabaseConfiguration {}
         </source>
-        <p>Use following configuration:</p>
+
+        <p>To configure a check that allows missing comments for classes annotated with
+          <code>@Annotation</code> and <code>@MyClass.Annotation</code>:
+        </p>
         <source>
 &lt;module name="MissingJavadocType"&gt;
-  &lt;property name="skipAnnotations" value="SpringBootApplication,Configuration"/&gt;
+  &lt;property name="skipAnnotations" value="Annotation,MyClass.Annotation"/&gt;
 &lt;/module&gt;
         </source>
+        <p>
+          Example:
+        </p>
+        <source>
+@Annotation // ok
+class Class1 {}
+
+@MyClass.Annotation // ok
+class Class2 {}
+
+@com.mycompany.MyClass.Annotation // violation, as this form is missed in config
+class Class3 {}
+        </source>
       </subsection>
 
       <subsection name="Example of Usage" id="MissingJavadocType_Example_of_Usage">