Issue #13732: Add Examples Macro Support to All Checks

checkstyle · Sep 16, 2023 · d94f78f · d94f78f
1 parent 83cc6e4
commit d94f78f
Show file tree

Hide file tree

Showing 22 changed files with 746 additions and 1,319 deletions.
diff --git a/config/checkstyle-non-main-files-suppressions.xml b/config/checkstyle-non-main-files-suppressions.xml
@@ -168,36 +168,6 @@
   <suppress id="workflowJobStepSpacing" files="^.((?!github[\\/]workflows[\\/]).)*$" />
 
   <!-- Examples macro suppressions -->
-  <suppress id="exampleMacroMustExist"
-         files="src[\\/]xdocs[\\/]checks[\\/]annotation[\\/]annotationlocation.xml.template"/>
-  <suppress id="exampleMacroMustExist"
-         files="src[\\/]xdocs[\\/]checks[\\/]annotation[\\/]annotationonsameline.xml.template"/>
-  <suppress id="exampleMacroMustExist"
-         files="src[\\/]xdocs[\\/]checks[\\/]annotation[\\/]annotationusestyle.xml.template"/>
-  <suppress id="exampleMacroMustExist"
-         files="src[\\/]xdocs[\\/]checks[\\/]annotation[\\/]missingdeprecated.xml.template"/>
-  <suppress id="exampleMacroMustExist"
-         files="src[\\/]xdocs[\\/]checks[\\/]annotation[\\/]missingoverride.xml.template"/>
-  <suppress id="exampleMacroMustExist"
-         files="src[\\/]xdocs[\\/]checks[\\/]annotation[\\/]suppresswarnings.xml.template"/>
-  <suppress id="exampleMacroMustExist"
-         files="src[\\/]xdocs[\\/]checks[\\/]blocks[\\/]avoidnestedblocks.xml.template"/>
-  <suppress id="exampleMacroMustExist"
-         files="src[\\/]xdocs[\\/]checks[\\/]blocks[\\/]emptyblock.xml.template"/>
-  <suppress id="exampleMacroMustExist"
-         files="src[\\/]xdocs[\\/]checks[\\/]blocks[\\/]emptycatchblock.xml.template"/>
-  <suppress id="exampleMacroMustExist"
-         files="src[\\/]xdocs[\\/]checks[\\/]blocks[\\/]leftcurly.xml.template"/>
-  <suppress id="exampleMacroMustExist"
-         files="src[\\/]xdocs[\\/]checks[\\/]blocks[\\/]needbraces.xml.template"/>
-  <suppress id="exampleMacroMustExist"
-         files="src[\\/]xdocs[\\/]checks[\\/]blocks[\\/]rightcurly.xml.template"/>
-  <suppress id="exampleMacroMustExist"
-         files="src[\\/]xdocs[\\/]checks[\\/]design[\\/]designforextension.xml.template"/>
-  <suppress id="exampleMacroMustExist"
-         files="src[\\/]xdocs[\\/]checks[\\/]design[\\/]finalclass.xml.template"/>
-  <suppress id="exampleMacroMustExist"
-         files="src[\\/]xdocs[\\/]checks[\\/]design[\\/]hideutilityclassconstructor.xml.template"/>
   <suppress id="exampleMacroMustExist"
          files="src[\\/]xdocs[\\/]checks[\\/]imports[\\/]importcontrol.xml.template"/>
   <suppress id="exampleMacroMustExist"

diff --git a/...sources/com/puppycrawl/tools/checkstyle/checks/annotation/annotationlocation/Example4.txt b/...sources/com/puppycrawl/tools/checkstyle/checks/annotation/annotationlocation/Example4.txt
@@ -1,4 +1,4 @@
-/*
+/*xml
 <module name="Checker">
   <module name="TreeWalker">
     <module name="AnnotationLocation">

diff --git a/src/xdocs/checks/annotation/annotationlocation.xml b/src/xdocs/checks/annotation/annotationlocation.xml
@@ -132,108 +132,125 @@ public String getNameIfPresent() { ... }
       </subsection>
 
       <subsection name="Examples" id="Examples">
-        <p>
+        <p id="Example1-config">
           To configure the default check to allow one single parameterless annotation on the same
             line:
         </p>
         <source>
-&lt;module name=&quot;AnnotationLocation&quot;/&gt;
+&lt;module name=&quot;Checker&quot;&gt;
+  &lt;module name=&quot;TreeWalker&quot;&gt;
+    &lt;module name=&quot;AnnotationLocation&quot;/&gt;
+  &lt;/module&gt;
+&lt;/module&gt;
         </source>
-        <p>
-          Example for above configuration:
-        </p>
+        <p id="Example1-code">Example:</p>
         <source>
-@NotNull private boolean field1; //ok
-@Override public int hashCode() { return 1; } //ok
-@NotNull //ok
-private boolean field2;
-@Override //ok
-public boolean equals(Object obj) { return true; }
-@Mock DataLoader loader; //ok
-@SuppressWarnings(&quot;deprecation&quot;) DataLoader loader; //violation
-@SuppressWarnings(&quot;deprecation&quot;) public int foo() { return 1; } //violation
-@NotNull @Mock DataLoader loader; //violation
+class Example1 {
+  @NotNull private boolean field1; //ok
+  @Override public int hashCode() { return 1; } //ok
+  @NotNull //ok
+  private boolean field2;
+  @Override //ok
+  public boolean equals(Object obj) { return true; }
+  @Mock
+  DataLoader loader; //ok
+  @SuppressWarnings(&quot;deprecation&quot;) DataLoader loader; //violation
+  @SuppressWarnings(&quot;deprecation&quot;) public int foo() { return 1; } //violation
+  @NotNull @Mock DataLoader loader; //violation
+}
         </source>
-        <p>
+        <p id="Example2-config">
           Use the following configuration to allow multiple annotations on the same line:
         </p>
         <source>
-&lt;module name=&quot;AnnotationLocation&quot;&gt;
-  &lt;property name=&quot;allowSamelineMultipleAnnotations&quot; value=&quot;true&quot;/&gt;
-  &lt;property name=&quot;allowSamelineSingleParameterlessAnnotation&quot;
-    value=&quot;false&quot;/&gt;
-  &lt;property name=&quot;allowSamelineParameterizedAnnotation&quot; value=&quot;false&quot;/&gt;
+&lt;module name=&quot;Checker&quot;&gt;
+  &lt;module name=&quot;TreeWalker&quot;&gt;
+    &lt;module name=&quot;AnnotationLocation&quot;&gt;
+      &lt;property name=&quot;allowSamelineMultipleAnnotations&quot; value=&quot;true&quot;/&gt;
+      &lt;property name=&quot;allowSamelineSingleParameterlessAnnotation&quot;
+                value=&quot;false&quot;/&gt;
+      &lt;property name=&quot;allowSamelineParameterizedAnnotation&quot; value=&quot;false&quot;/&gt;
+    &lt;/module&gt;
+  &lt;/module&gt;
 &lt;/module&gt;
         </source>
-        <p>
-          Example to allow any location multiple annotations:
-        </p>
+        <p id="Example2-code">Example:</p>
         <source>
-@NotNull private boolean field1; //ok
-@Override public int hashCode() { return 1; } //ok
-@NotNull //ok
-private boolean field2;
-@Override //ok
-public boolean equals(Object obj) { return true; }
-@Mock DataLoader loader; //ok
-@SuppressWarnings(&quot;deprecation&quot;) DataLoader loader; //ok
-@SuppressWarnings(&quot;deprecation&quot;) public int foo() { return 1; } //ok
-@NotNull @Mock DataLoader loader; //ok
+class Example2 {
+  @NotNull private boolean field1; //ok
+  @Override public int hashCode() { return 1; } //ok
+  @NotNull //ok
+  private boolean field2;
+  @Override //ok
+  public boolean equals(Object obj) { return true; }
+  @Mock DataLoader loader; //ok
+  @SuppressWarnings(&quot;deprecation&quot;) DataLoader loader; //ok
+  @SuppressWarnings(&quot;deprecation&quot;) public int foo() { return 1; } //ok
+  @NotNull @Mock DataLoader loader; //ok
+}
         </source>
-        <p>
+        <p id="Example3-config">
           Use the following configuration to allow only one and only parameterized annotation
           on the same line:
         </p>
         <source>
-&lt;module name=&quot;AnnotationLocation&quot;&gt;
-  &lt;property name=&quot;allowSamelineMultipleAnnotations&quot; value=&quot;false&quot;/&gt;
-  &lt;property name=&quot;allowSamelineSingleParameterlessAnnotation&quot;
-    value=&quot;false&quot;/&gt;
-  &lt;property name=&quot;allowSamelineParameterizedAnnotation&quot; value=&quot;true&quot;/&gt;
+&lt;module name=&quot;Checker&quot;&gt;
+  &lt;module name=&quot;TreeWalker&quot;&gt;
+    &lt;module name=&quot;AnnotationLocation&quot;&gt;
+      &lt;property name=&quot;allowSamelineMultipleAnnotations&quot; value=&quot;false&quot;/&gt;
+      &lt;property name=&quot;allowSamelineSingleParameterlessAnnotation&quot;
+                value=&quot;false&quot;/&gt;
+      &lt;property name=&quot;allowSamelineParameterizedAnnotation&quot; value=&quot;true&quot;/&gt;
+    &lt;/module&gt;
+  &lt;/module&gt;
 &lt;/module&gt;
         </source>
-        <p>
-          Example to allow only one and only parameterized annotation on the same line:
-        </p>
+        <p id="Example3-code">Example:</p>
         <source>
-@NotNull private boolean field1; //violation
-@Override public int hashCode() { return 1; } //violation
-@NotNull //ok
-private boolean field2;
-@Override //ok
-public boolean equals(Object obj) { return true; }
-@Mock DataLoader loader; //violation
-@SuppressWarnings(&quot;deprecation&quot;) DataLoader loader; //ok
-@SuppressWarnings(&quot;deprecation&quot;) public int foo() { return 1; } //ok
-@NotNull @Mock DataLoader loader; //violation
+class Example3 {
+  @NotNull private boolean field1; //violation
+  @Override public int hashCode() { return 1; } //violation
+  @NotNull //ok
+  private boolean field2;
+  @Override //ok
+  public boolean equals(Object obj) { return true; }
+  @Mock DataLoader loader; //violation
+  @SuppressWarnings(&quot;deprecation&quot;) DataLoader loader; //ok
+  @SuppressWarnings(&quot;deprecation&quot;) public int foo() { return 1; } //ok
+  @NotNull @Mock DataLoader loader; //violation
+}
         </source>
-        <p>
+        <p id="Example4-config">
           Use the following configuration to only validate annotations on methods to allow one
           single parameterless annotation on the same line:
         </p>
         <source>
-&lt;module name=&quot;AnnotationLocation&quot;&gt;
-  &lt;property name=&quot;tokens&quot; value=&quot;METHOD_DEF&quot;/&gt;
-  &lt;property name=&quot;allowSamelineMultipleAnnotations&quot; value=&quot;false&quot;/&gt;
-  &lt;property name=&quot;allowSamelineSingleParameterlessAnnotation&quot;
-    value=&quot;true&quot;/&gt;
-  &lt;property name=&quot;allowSamelineParameterizedAnnotation&quot; value=&quot;false&quot;/&gt;
+&lt;module name=&quot;Checker&quot;&gt;
+  &lt;module name=&quot;TreeWalker&quot;&gt;
+    &lt;module name=&quot;AnnotationLocation&quot;&gt;
+      &lt;property name=&quot;tokens&quot; value=&quot;METHOD_DEF&quot;/&gt;
+      &lt;property name=&quot;allowSamelineMultipleAnnotations&quot; value=&quot;false&quot;/&gt;
+      &lt;property name=&quot;allowSamelineSingleParameterlessAnnotation&quot;
+                value=&quot;true&quot;/&gt;
+      &lt;property name=&quot;allowSamelineParameterizedAnnotation&quot; value=&quot;false&quot;/&gt;
+    &lt;/module&gt;
+  &lt;/module&gt;
 &lt;/module&gt;
         </source>
-        <p>
-          Example for above configuration to check only methods:
-        </p>
+        <p id="Example4-code">Example:</p>
         <source>
-@NotNull private boolean field1; //ok
-@Override public int hashCode() { return 1; } //ok
-@NotNull //ok
-private boolean field2;
-@Override //ok
-public boolean equals(Object obj) { return true; }
-@Mock DataLoader loader; //ok
-@SuppressWarnings(&quot;deprecation&quot;) DataLoader loader; //ok
-@SuppressWarnings(&quot;deprecation&quot;) public int foo() { return 1; } //violation
-@NotNull @Mock DataLoader loader; //ok
+class Example4 {
+  @NotNull private boolean field1; //ok
+  @Override public int hashCode() { return 1; } //ok
+  @NotNull //ok
+  private boolean field2;
+  @Override //ok
+  public boolean equals(Object obj) { return true; }
+  @Mock DataLoader loader; //ok
+  @SuppressWarnings(&quot;deprecation&quot;) DataLoader loader; //ok
+  @SuppressWarnings(&quot;deprecation&quot;) public int foo() { return 1; } //violation
+  @NotNull @Mock DataLoader loader; //ok
+}
         </source>
       </subsection>
 

diff --git a/src/xdocs/checks/annotation/annotationlocation.xml.template b/src/xdocs/checks/annotation/annotationlocation.xml.template
@@ -51,109 +51,65 @@ public String getNameIfPresent() { ... }
       </subsection>
 
       <subsection name="Examples" id="Examples">
-        <p>
+        <p id="Example1-config">
           To configure the default check to allow one single parameterless annotation on the same
             line:
         </p>
-        <source>
-&lt;module name="AnnotationLocation"/&gt;
-        </source>
-        <p>
-          Example for above configuration:
-        </p>
-        <source>
-@NotNull private boolean field1; //ok
-@Override public int hashCode() { return 1; } //ok
-@NotNull //ok
-private boolean field2;
-@Override //ok
-public boolean equals(Object obj) { return true; }
-@Mock DataLoader loader; //ok
-@SuppressWarnings("deprecation") DataLoader loader; //violation
-@SuppressWarnings("deprecation") public int foo() { return 1; } //violation
-@NotNull @Mock DataLoader loader; //violation
-        </source>
-        <p>
+        <macro name="example">
+          <param name="path"
+                 value="resources/com/puppycrawl/tools/checkstyle/checks/annotation/annotationlocation/Example1.txt"/>
+          <param name="type" value="config"/>
+        </macro>
+        <p id="Example1-code">Example:</p>
+        <macro name="example">
+          <param name="path"
+                   value="resources/com/puppycrawl/tools/checkstyle/checks/annotation/annotationlocation/Example1.txt"/>
+            <param name="type" value="code"/>
+        </macro>
+        <p id="Example2-config">
           Use the following configuration to allow multiple annotations on the same line:
         </p>
-        <source>
-&lt;module name="AnnotationLocation"&gt;
-  &lt;property name="allowSamelineMultipleAnnotations" value="true"/&gt;
-  &lt;property name="allowSamelineSingleParameterlessAnnotation"
-    value="false"/&gt;
-  &lt;property name="allowSamelineParameterizedAnnotation" value="false"/&gt;
-&lt;/module&gt;
-        </source>
-        <p>
-          Example to allow any location multiple annotations:
-        </p>
-        <source>
-@NotNull private boolean field1; //ok
-@Override public int hashCode() { return 1; } //ok
-@NotNull //ok
-private boolean field2;
-@Override //ok
-public boolean equals(Object obj) { return true; }
-@Mock DataLoader loader; //ok
-@SuppressWarnings("deprecation") DataLoader loader; //ok
-@SuppressWarnings("deprecation") public int foo() { return 1; } //ok
-@NotNull @Mock DataLoader loader; //ok
-        </source>
-        <p>
+        <macro name="example">
+          <param name="path"
+                 value="resources/com/puppycrawl/tools/checkstyle/checks/annotation/annotationlocation/Example2.txt"/>
+          <param name="type" value="config"/>
+        </macro>
+        <p id="Example2-code">Example:</p>
+        <macro name="example">
+          <param name="path"
+                   value="resources/com/puppycrawl/tools/checkstyle/checks/annotation/annotationlocation/Example2.txt"/>
+            <param name="type" value="code"/>
+        </macro>
+        <p id="Example3-config">
           Use the following configuration to allow only one and only parameterized annotation
           on the same line:
         </p>
-        <source>
-&lt;module name="AnnotationLocation"&gt;
-  &lt;property name="allowSamelineMultipleAnnotations" value="false"/&gt;
-  &lt;property name="allowSamelineSingleParameterlessAnnotation"
-    value="false"/&gt;
-  &lt;property name="allowSamelineParameterizedAnnotation" value="true"/&gt;
-&lt;/module&gt;
-        </source>
-        <p>
-          Example to allow only one and only parameterized annotation on the same line:
-        </p>
-        <source>
-@NotNull private boolean field1; //violation
-@Override public int hashCode() { return 1; } //violation
-@NotNull //ok
-private boolean field2;
-@Override //ok
-public boolean equals(Object obj) { return true; }
-@Mock DataLoader loader; //violation
-@SuppressWarnings("deprecation") DataLoader loader; //ok
-@SuppressWarnings("deprecation") public int foo() { return 1; } //ok
-@NotNull @Mock DataLoader loader; //violation
-        </source>
-        <p>
+        <macro name="example">
+          <param name="path"
+                 value="resources/com/puppycrawl/tools/checkstyle/checks/annotation/annotationlocation/Example3.txt"/>
+          <param name="type" value="config"/>
+        </macro>
+        <p id="Example3-code">Example:</p>
+        <macro name="example">
+          <param name="path"
+                   value="resources/com/puppycrawl/tools/checkstyle/checks/annotation/annotationlocation/Example3.txt"/>
+            <param name="type" value="code"/>
+        </macro>
+        <p id="Example4-config">
           Use the following configuration to only validate annotations on methods to allow one
           single parameterless annotation on the same line:
         </p>
-        <source>
-&lt;module name="AnnotationLocation"&gt;
-  &lt;property name="tokens" value="METHOD_DEF"/&gt;
-  &lt;property name="allowSamelineMultipleAnnotations" value="false"/&gt;
-  &lt;property name="allowSamelineSingleParameterlessAnnotation"
-    value="true"/&gt;
-  &lt;property name="allowSamelineParameterizedAnnotation" value="false"/&gt;
-&lt;/module&gt;
-        </source>
-        <p>
-          Example for above configuration to check only methods:
-        </p>
-        <source>
-@NotNull private boolean field1; //ok
-@Override public int hashCode() { return 1; } //ok
-@NotNull //ok
-private boolean field2;
-@Override //ok
-public boolean equals(Object obj) { return true; }
-@Mock DataLoader loader; //ok
-@SuppressWarnings("deprecation") DataLoader loader; //ok
-@SuppressWarnings("deprecation") public int foo() { return 1; } //violation
-@NotNull @Mock DataLoader loader; //ok
-        </source>
+        <macro name="example">
+          <param name="path"
+                 value="resources/com/puppycrawl/tools/checkstyle/checks/annotation/annotationlocation/Example4.txt"/>
+          <param name="type" value="config"/>
+        </macro>
+        <p id="Example4-code">Example:</p>
+        <macro name="example">
+          <param name="path"
+                   value="resources/com/puppycrawl/tools/checkstyle/checks/annotation/annotationlocation/Example4.txt"/>
+            <param name="type" value="code"/>
+        </macro>
       </subsection>
 
       <subsection name="Example of Usage" id="Example_of_Usage">