Skip to content

Commit

Permalink
Issue checkstyle#13693: migrate some javadoc to macroses
Browse files Browse the repository at this point in the history
  • Loading branch information
@romani @nrmancuso
romani authored and nrmancuso committed Dec 31, 2023
1 parent a2ecdde commit 43351bf
Show file tree
Hide file tree
Showing 23 changed files with 129 additions and 677 deletions.
20 changes: 0 additions & 20 deletions config/checkstyle-non-main-files-suppressions.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -257,26 +257,6 @@
files="src[\\/]xdocs[\\/]checks[\\/]javadoc[\\/]javadocparagraph.xml.template"/>
<suppress id="propertiesMacroMustExist"
files="src[\\/]xdocs[\\/]checks[\\/]javadoc[\\/]javadocstyle.xml.template"/>
<suppress id="propertiesMacroMustExist"
files="src[\\/]xdocs[\\/]checks[\\/]javadoc[\\/]javadoctagcontinuationindentation.xml.template"/>
<suppress id="propertiesMacroMustExist"
files="src[\\/]xdocs[\\/]checks[\\/]javadoc[\\/]javadoctype.xml.template"/>
<suppress id="propertiesMacroMustExist"
files="src[\\/]xdocs[\\/]checks[\\/]javadoc[\\/]javadocvariable.xml.template"/>
<suppress id="propertiesMacroMustExist"
files="src[\\/]xdocs[\\/]checks[\\/]javadoc[\\/]missingjavadocmethod.xml.template"/>
<suppress id="propertiesMacroMustExist"
files="src[\\/]xdocs[\\/]checks[\\/]javadoc[\\/]missingjavadoctype.xml.template"/>
<suppress id="propertiesMacroMustExist"
files="src[\\/]xdocs[\\/]checks[\\/]javadoc[\\/]nonemptyatclausedescription.xml.template"/>
<suppress id="propertiesMacroMustExist"
files="src[\\/]xdocs[\\/]checks[\\/]javadoc[\\/]requireemptylinebeforeblocktaggroup.xml.template"/>
<suppress id="propertiesMacroMustExist"
files="src[\\/]xdocs[\\/]checks[\\/]javadoc[\\/]singlelinejavadoc.xml.template"/>
<suppress id="propertiesMacroMustExist"
files="src[\\/]xdocs[\\/]checks[\\/]javadoc[\\/]summaryjavadoc.xml.template"/>
<suppress id="propertiesMacroMustExist"
files="src[\\/]xdocs[\\/]checks[\\/]javadoc[\\/]writetag.xml.template"/>
<suppress id="propertiesMacroMustExist"
files="src[\\/]xdocs[\\/]checks[\\/]misc[\\/]orderedproperties.xml.template"/>
<suppress id="propertiesMacroMustExist"
Expand Down
3 changes: 3 additions & 0 deletions src/main/java/com/puppycrawl/tools/checkstyle/site/PropertiesMacro.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -237,6 +237,9 @@ private static List<String> orderProperties(Set<String> properties) {
if (orderProperties.remove(TOKENS_PROPERTY)) {
orderProperties.add(TOKENS_PROPERTY);
}
if (orderProperties.remove(SiteUtil.JAVADOC_TOKENS)) {
orderProperties.add(SiteUtil.JAVADOC_TOKENS);
}
return List.copyOf(orderProperties);

}
Expand Down
2 changes: 2 additions & 0 deletions src/main/java/com/puppycrawl/tools/checkstyle/site/SiteUtil.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -241,6 +241,8 @@ public final class SiteUtil {
// until https://github.com/checkstyle/checkstyle/issues/14052
Map.entry("JavadocBlockTagLocationCheck.violateExecutionOnNonTightHtml", V824),
Map.entry("JavadocMissingLeadingAsteriskCheck.violateExecutionOnNonTightHtml", "8.38"),
Map.entry(
"RequireEmptyLineBeforeBlockTagGroupCheck.violateExecutionOnNonTightHtml", "8.36"),
Map.entry("ParenPadCheck.option", VERSION_3_0),
Map.entry("TypecastParenPadCheck.option", VERSION_3_2),
Map.entry("FileLengthCheck.fileExtensions", VERSION_5_0),
Expand Down
10 changes: 3 additions & 7 deletions src/xdocs/checks/javadoc/javadoctagcontinuationindentation.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,13 +38,9 @@
</tr>
<tr>
<td>violateExecutionOnNonTightHtml</td>
<td>
Control when to print violations if the Javadoc being examined by this check
violates the tight html rules defined at
<a href="../../writingjavadocchecks.html#Tight-HTML_rules">Tight-HTML Rules</a>.
</td>
<td><a href="../../property_types.html#boolean">boolean</a>
</td>
<td>Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at <a href="../../writingjavadocchecks.html#Tight-HTML_rules">
Tight-HTML Rules</a>.</td>
<td><a href="../../property_types.html#boolean">boolean</a></td>
<td><code>false</code></td>
<td>8.3</td>
</tr>
Expand Down
32 changes: 4 additions & 28 deletions src/xdocs/checks/javadoc/javadoctagcontinuationindentation.xml.template
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,34 +21,10 @@

<subsection name="Properties" id="Properties">
<div class="wrapper">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
<th>since</th>
</tr>
<tr>
<td>offset</td>
<td>Specify how many spaces to use for new indentation level.</td>
<td><a href="../../property_types.html#int">int</a></td>
<td><code>4</code></td>
<td>6.0</td>
</tr>
<tr>
<td>violateExecutionOnNonTightHtml</td>
<td>
Control when to print violations if the Javadoc being examined by this check
violates the tight html rules defined at
<a href="../../writingjavadocchecks.html#Tight-HTML_rules">Tight-HTML Rules</a>.
</td>
<td><a href="../../property_types.html#boolean">boolean</a>
</td>
<td><code>false</code></td>
<td>8.3</td>
</tr>
</table>
<macro name="properties">
<param name="modulePath"
value="src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocTagContinuationIndentationCheck.java"/>
</macro>
</div>
</subsection>

Expand Down
35 changes: 15 additions & 20 deletions src/xdocs/checks/javadoc/javadoctype.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,7 @@
</tr>
<tr>
<td>allowMissingParamTags</td>
<td>Control whether to ignore violations when a class has type parameters
but does not have matching param tags in the Javadoc.</td>
<td>Control whether to ignore violations when a class has type parameters but does not have matching param tags in the Javadoc.</td>
<td><a href="../../property_types.html#boolean">boolean</a></td>
<td><code>false</code></td>
<td>4.0</td>
Expand All @@ -63,10 +62,7 @@
</tr>
<tr>
<td>allowedAnnotations</td>
<td>
Specify annotations that allow skipping validation at all.
Only short names are allowed, e.g. <code>Generated</code>.
</td>
<td>Specify annotations that allow skipping validation at all. Only short names are allowed, e.g. <code>Generated</code>.</td>
<td><a href="../../property_types.html#String.5B.5D">String[]</a></td>
<td><code>Generated</code></td>
<td>8.15</td>
Expand Down Expand Up @@ -102,31 +98,30 @@
<tr>
<td>tokens</td>
<td>tokens to check</td>
<td>
subset of tokens
<td>subset of tokens
<a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF">
INTERFACE_DEF</a>
INTERFACE_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">
CLASS_DEF</a>
CLASS_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF">
ENUM_DEF</a>
ENUM_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF">
ANNOTATION_DEF</a>
,<a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#RECORD_DEF">
RECORD_DEF</a>
ANNOTATION_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#RECORD_DEF">
RECORD_DEF</a>
.
</td>
<td>
<a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF">
INTERFACE_DEF</a>
INTERFACE_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">
CLASS_DEF</a>
CLASS_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF">
ENUM_DEF</a>
ENUM_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF">
ANNOTATION_DEF</a>
,<a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#RECORD_DEF">
RECORD_DEF</a>
ANNOTATION_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#RECORD_DEF">
RECORD_DEF</a>
.
</td>
<td>3.0</td>
Expand Down
98 changes: 4 additions & 94 deletions src/xdocs/checks/javadoc/javadoctype.xml.template
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,100 +38,10 @@

<subsection name="Properties" id="Properties">
<div class="wrapper">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
<th>since</th>
</tr>
<tr>
<td>allowMissingParamTags</td>
<td>Control whether to ignore violations when a class has type parameters
but does not have matching param tags in the Javadoc.</td>
<td><a href="../../property_types.html#boolean">boolean</a></td>
<td><code>false</code></td>
<td>4.0</td>
</tr>
<tr>
<td>allowUnknownTags</td>
<td>Control whether to ignore violations when a Javadoc tag is not recognised.</td>
<td><a href="../../property_types.html#boolean">boolean</a></td>
<td><code>false</code></td>
<td>5.1</td>
</tr>
<tr>
<td>allowedAnnotations</td>
<td>
Specify annotations that allow skipping validation at all.
Only short names are allowed, e.g. <code>Generated</code>.
</td>
<td><a href="../../property_types.html#String.5B.5D">String[]</a></td>
<td><code>Generated</code></td>
<td>8.15</td>
</tr>
<tr>
<td>authorFormat</td>
<td>Specify the pattern for <code>@author</code> tag.</td>
<td><a href="../../property_types.html#Pattern">Pattern</a></td>
<td><code>null</code></td>
<td>3.0</td>
</tr>
<tr>
<td>excludeScope</td>
<td>Specify the visibility scope where Javadoc comments are not checked.</td>
<td><a href="../../property_types.html#Scope">Scope</a></td>
<td><code>null</code></td>
<td>3.4</td>
</tr>
<tr>
<td>scope</td>
<td>Specify the visibility scope where Javadoc comments are checked.</td>
<td><a href="../../property_types.html#Scope">Scope</a></td>
<td><code>private</code></td>
<td>3.0</td>
</tr>
<tr>
<td>versionFormat</td>
<td>Specify the pattern for <code>@version</code> tag.</td>
<td><a href="../../property_types.html#Pattern">Pattern</a></td>
<td><code>null</code></td>
<td>3.0</td>
</tr>
<tr>
<td>tokens</td>
<td>tokens to check</td>
<td>
subset of tokens
<a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF">
INTERFACE_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">
CLASS_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF">
ENUM_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF">
ANNOTATION_DEF</a>
,<a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#RECORD_DEF">
RECORD_DEF</a>
.
</td>
<td>
<a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF">
INTERFACE_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">
CLASS_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF">
ENUM_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF">
ANNOTATION_DEF</a>
,<a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#RECORD_DEF">
RECORD_DEF</a>
.
</td>
<td>3.0</td>
</tr>
</table>
<macro name="properties">
<param name="modulePath"
value="src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocTypeCheck.java"/>
</macro>
</div>
</subsection>

Expand Down
6 changes: 2 additions & 4 deletions src/xdocs/checks/javadoc/javadocvariable.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,14 +51,12 @@
<td>tokens to check</td>
<td>subset of tokens
<a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_CONSTANT_DEF">
ENUM_CONSTANT_DEF
</a>
ENUM_CONSTANT_DEF</a>
.
</td>
<td>
<a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_CONSTANT_DEF">
ENUM_CONSTANT_DEF
</a>
ENUM_CONSTANT_DEF</a>
.
</td>
<td>3.0</td>
Expand Down
51 changes: 4 additions & 47 deletions src/xdocs/checks/javadoc/javadocvariable.xml.template
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,53 +17,10 @@

<subsection name="Properties" id="Properties">
<div class="wrapper">
<table>
<tr>
<th>name</th>
<th>description</th>
<th>type</th>
<th>default value</th>
<th>since</th>
</tr>
<tr>
<td>excludeScope</td>
<td>Specify the visibility scope where Javadoc comments are not checked.</td>
<td><a href="../../property_types.html#Scope">Scope</a></td>
<td><code>null</code></td>
<td>3.4</td>
</tr>
<tr>
<td>ignoreNamePattern</td>
<td>Specify the regexp to define variable names to ignore.</td>
<td><a href="../../property_types.html#Pattern">Pattern</a></td>
<td><code>null</code></td>
<td>5.8</td>
</tr>
<tr>
<td>scope</td>
<td>Specify the visibility scope where Javadoc comments are checked.</td>
<td><a href="../../property_types.html#Scope">Scope</a></td>
<td><code>private</code></td>
<td>3.0</td>
</tr>
<tr>
<td>tokens</td>
<td>tokens to check</td>
<td>subset of tokens
<a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_CONSTANT_DEF">
ENUM_CONSTANT_DEF
</a>
.
</td>
<td>
<a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_CONSTANT_DEF">
ENUM_CONSTANT_DEF
</a>
.
</td>
<td>3.0</td>
</tr>
</table>
<macro name="properties">
<param name="modulePath"
value="src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheck.java"/>
</macro>
</div>
</subsection>

Expand Down
25 changes: 10 additions & 15 deletions src/xdocs/checks/javadoc/missingjavadocmethod.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,10 +61,7 @@ public boolean isSomething()
</tr>
<tr>
<td>allowMissingPropertyJavadoc</td>
<td>
Control whether to allow missing Javadoc on accessor methods for
properties (setters and getters).
</td>
<td>Control whether to allow missing Javadoc on accessor methods for properties (setters and getters).</td>
<td><a href="../../property_types.html#boolean">boolean</a></td>
<td><code>false</code></td>
<td>8.21</td>
Expand Down Expand Up @@ -107,28 +104,26 @@ public boolean isSomething()
<tr>
<td>tokens</td>
<td>tokens to check</td>

<td>
subset of tokens
<td>subset of tokens
<a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">
METHOD_DEF</a>
METHOD_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">
CTOR_DEF</a>
CTOR_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_FIELD_DEF">
ANNOTATION_FIELD_DEF</a>
ANNOTATION_FIELD_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#COMPACT_CTOR_DEF">
COMPACT_CTOR_DEF</a>
COMPACT_CTOR_DEF</a>
.
</td>
<td>
<a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">
METHOD_DEF</a>
METHOD_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">
CTOR_DEF</a>
CTOR_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_FIELD_DEF">
ANNOTATION_FIELD_DEF</a>
ANNOTATION_FIELD_DEF</a>
, <a href="../../apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#COMPACT_CTOR_DEF">
COMPACT_CTOR_DEF</a>
COMPACT_CTOR_DEF</a>
.
</td>
<td>8.21</td>
Expand Down
Loading

0 comments on commit 43351bf

Please sign in to comment.