From caa907fa69bc25490044bf9160681d1534f97f8b Mon Sep 17 00:00:00 2001 From: stoyanK7 Date: Wed, 13 Jul 2022 20:02:01 +0300 Subject: [PATCH] Issue #11736: Update doc for MissingJavadocTypeCheck --- .../javadoc/MissingJavadocTypeCheck.java | 39 +++++++++++++++---- .../javadoc/MissingJavadocTypeCheck.xml | 3 +- src/xdocs/config_javadoc.xml | 32 ++++++++++++--- 3 files changed, 61 insertions(+), 13 deletions(-) diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/MissingJavadocTypeCheck.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/MissingJavadocTypeCheck.java index 6381efcac63..286167a5da3 100644 --- a/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/MissingJavadocTypeCheck.java +++ b/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/MissingJavadocTypeCheck.java @@ -53,7 +53,8 @@ * *
  • * 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}. *
    • @@ -126,8 +127,16 @@ * class PackagePrivateClass {} * *

    - * 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}: + *

    + * 
    + * <module name="MissingJavadocType">
+ *   <property name="skipAnnotations" value="SpringBootApplication,Configuration"/>
+ * </module>
+ *
    + *

    + * Example: *

    * 
      * @SpringBootApplication // no violations about missing comment on class
@@ -137,14 +146,28 @@
  * class DatabaseConfiguration {}
  *
    *

    - * Use following configuration: + * To configure a check that allows missing comments for classes annotated with {@code @Annotation} + * and {@code @MyClass.Annotation}: *

    * 
      * <module name="MissingJavadocType">
- *   <property name="skipAnnotations" value="SpringBootApplication,Configuration"/>
+ *   <property name="skipAnnotations" value="Annotation,MyClass.Annotation"/>
  * </module>
  *
    *

    + * Example: + *

    + * 
    + * @Annotation // ok
+ * class Class1 {}
+ *
+ * @MyClass.Annotation // ok
+ * class Class2 {}
+ *
+ * @com.mycompany.MyClass.Annotation // violation, as this form is missed in config
+ * class Class3 {}
+ *
    + *

    * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} *

    *

    @@ -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 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. */ diff --git a/src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/javadoc/MissingJavadocTypeCheck.xml b/src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/javadoc/MissingJavadocTypeCheck.xml index 44fc5f0f128..1989ce49353 100644 --- a/src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/javadoc/MissingJavadocTypeCheck.xml +++ b/src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/javadoc/MissingJavadocTypeCheck.xml @@ -24,7 +24,8 @@ name="skipAnnotations" type="java.lang.String[]"> 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. skipAnnotations specify annotations that allow missed documentation. - Only short names are allowed, e.g. Generated. + If annotation is present in target sources in multiple forms of qualified + name, all forms should be listed in this property. String[] Generated @@ -2979,23 +2980,44 @@ protected class PublicClass {} class PackagePrivateClass {} -

    - Example that allows missing comments for classes annotated with +

    To configure a check that allows missing comments for classes annotated with @SpringBootApplication and @Configuration:

    +<module name="MissingJavadocType"> + <property name="skipAnnotations" value="SpringBootApplication,Configuration"/> +</module> + +

    Example:

    + @SpringBootApplication // no violations about missing comment on class public class Application {} @Configuration // no violations about missing comment on class class DatabaseConfiguration {} -

    Use following configuration:

    + +

    To configure a check that allows missing comments for classes annotated with + @Annotation and @MyClass.Annotation: +

    <module name="MissingJavadocType"> - <property name="skipAnnotations" value="SpringBootApplication,Configuration"/> + <property name="skipAnnotations" value="Annotation,MyClass.Annotation"/> </module> +

    + Example: +

    + +@Annotation // ok +class Class1 {} + +@MyClass.Annotation // ok +class Class2 {} + +@com.mycompany.MyClass.Annotation // violation, as this form is missed in config +class Class3 {} +