Skip to content
Permalink
Browse files
IGNITE-14591: Add javadoc validation to checkstyle plugin. (#98)
  • Loading branch information
AMashenkov committed Jul 19, 2021
1 parent 058af76 commit 66def972d61ae0a0eb6752f208cdb686c7fc9227
Show file tree
Hide file tree
Showing 4 changed files with 232 additions and 2 deletions.
@@ -28,9 +28,19 @@ Upon build completion, CLI tool can be found be under `modules/cli/target` direc
Code style is checked with [Apache Maven Checkstyle Plugin](https://maven.apache.org/plugins/maven-checkstyle-plugin/).
* [Checkstyle rules](check-rules/checkstyle-rules.xml)
* [Checkstyle suppressions](check-rules/checkstyle-suppressions.xml)
* [Checkstyle rules for javadocs](https://checkstyle.sourceforge.io/config_javadoc.html)

Run code style checks only:
```
mvn clean checkstyle:checkstyle-aggregate
```

Run javadoc style checks for public api only:
```
mvn clean checkstyle:checkstyle-aggregate -P javadoc-public-api
```
>ℹ `javadoc-public-api` profile is required for enabling checkstyle rules for public API javadoc.
Code style check result is generated at `target/site/checkstyle-aggregate.html`

### License headers
@@ -68,6 +78,7 @@ mvn integration-test -Dskip.surefire.tests

## Checking and generating Javadoc
Javadoc is generated and checked for correctness with [Maven Javadoc Plugin](https://maven.apache.org/plugins/maven-javadoc-plugin/).
(Javadoc style check is described above in [Code style](#code-style) section)

Check Javadoc is correct (precompilation is required for resolving internal dependencies):
```
@@ -0,0 +1,39 @@
<?xml version="1.0"?>

<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

<!DOCTYPE suppressions PUBLIC
"-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN"
"https://checkstyle.org/dtds/suppressions_1_2.dtd">

<!-- To be removed once all javadoc issues will be fixed. -->
<suppressions>
<suppress files="[/\\]examples[/\\]" checks=".*" />
<suppress files="[/\\]modules/api[/\\]" checks=".*" />
<suppress files="[/\\]modules/calcite[/\\]" checks=".*" />
<suppress files="[/\\]modules/cli[/\\]" checks=".*" />
<suppress files="[/\\]modules/core[/\\]" checks=".*" />
<suppress files="[/\\]modules/configuration-api[/\\]" checks=".*" />
<suppress files="[/\\]modules/raft-client[/\\]" checks=".*" />
<suppress files="[/\\]modules/network[/\\]" checks=".*" />
<suppress files="[/\\]modules/network-api[/\\]" checks=".*" />
<suppress files="[/\\]modules/rest[/\\]" checks=".*" />
<suppress files="[/\\]modules/runner[/\\]" checks=".*" />
<suppress files="[/\\]modules/schema[/\\]" checks=".*" />
<suppress files="[/\\]modules/table[/\\]" checks=".*" />
</suppressions>
@@ -0,0 +1,161 @@
<?xml version="1.0"?>

<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

<!DOCTYPE module PUBLIC
"-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
"http://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
<property name="charset" value="UTF-8"/>

<property name="fileExtensions" value="java"/>

<module name="BeforeExecutionExclusionFileFilter">
<property name="fileNamePattern" value=".*[\\/](test|internal)[\\/].*$"/>
</module>

<!-- SuppressWarning Filter. https://checkstyle.sourceforge.io/config_filters.html#SuppressWarningsFilter -->
<module name="SuppressWarningsFilter"/>

<!--
Checks that each Java package has a Javadoc file used for commenting.
By default it only allows a package-info.java file.
See: https://checkstyle.org/config_javadoc.html#JavadocPackage
-->
<module name="JavadocPackage" />

<module name="TreeWalker">
<!-- Handler for SuppressWarning Filter. https://checkstyle.sourceforge.io/config_filters.html#SuppressWarningsFilter -->
<module name="SuppressWarningsHolder"/>

<!--
Javdoc style checks.
-->

<!--
Checks the order of javadoc block-tags or javadoc tags.
See: https://checkstyle.org/config_javadoc.html#AtclauseOrder
-->
<module name="AtclauseOrder"/>

<!--
Checks that Javadocs are located at the correct position.
See: https://checkstyle.org/config_javadoc.html#InvalidJavadocPosition
-->
<module name="InvalidJavadocPosition"/>

<!--
Checks that a javadoc block tag (starts with @) appears only at the beginning of a line,
ignoring leading asterisks and white space.
This check ignores block tags in comments and inside inline tags {@code } and {@literal }.
See: https://checkstyle.org/config_javadoc.html#JavadocBlockTagLocation
-->
<module name="JavadocBlockTagLocation">
<!-- default tags -->
<property name="tags" value="author, deprecated, exception, hidden"/>
<property name="tags" value="param, provides, return, see, serial"/>
<property name="tags" value="serialData, serialField, since, throws"/>
<property name="tags" value="uses, version"/>
<!-- additional tags can be used in the project -->
<property name="tags" value="noinspection"/>
</module>

<!--
Checks that the Javadoc content begins from the same position for all Javadoc comments in the project.
Any leading asterisks and spaces are not counted as the beginning of the content and are therefore ignored.
https://checkstyle.org/config_javadoc.html#JavadocContentLocation
-->
<module name="JavadocContentLocationCheck"/>

<!--
Checks the Javadoc of a method or constructor.
See: https://checkstyle.org/config_javadoc.html#JavadocMethod
-->
<module name="JavadocMethod">
<property name="validateThrows" value="true"/>
</module>

<!--
Checks if the javadoc has leading asterisks on each line.
See: https://checkstyle.org/config_javadoc.html#JavadocMissingLeadingAsterisk
-->
<module name="JavadocMissingLeadingAsterisk"/>

<!--
Checks that there is at least one whitespace after the leading asterisk.
See: https://checkstyle.org/config_javadoc.html#JavadocMissingWhitespaceAfterAsterisk
-->
<module name="JavadocMissingWhitespaceAfterAsterisk"/>

<!--
Validates Javadoc comments to help ensure they are well formed.
See: https://checkstyle.org/config_javadoc.html#JavadocStyle
-->
<module name="JavadocStyle">
<property name="checkEmptyJavadoc" value="true"/>
</module>

<!--
Checks the Javadoc comments for type definitions.
See: https://checkstyle.org/config_javadoc.html#JavadocType
-->
<module name="JavadocType">
<property name="allowUnknownTags" value="true"/>
</module>

<!--
Checks that a variable has a Javadoc comment. Ignores serialVersionUID fields.
See: https://checkstyle.org/config_javadoc.html#JavadocVariable
-->
<module name="JavadocVariable"/>

<!--
Checks for missing Javadoc comments for a method or constructor.
See: https://checkstyle.org/config_javadoc.html#MissingJavadocMethod
-->
<module name="MissingJavadocMethod">
<property name="allowedAnnotations" value=""/>
</module>

<!--
Checks for missing Javadoc comments for interface, and annotation interface definitions.
See: https://checkstyle.org/config_javadoc.html#MissingJavadocType
-->
<module name="MissingJavadocType"/>

<!--
Checks that the block tag is followed by description.
See: https://checkstyle.org/config_javadoc.html#NonEmptyAtclauseDescription
-->
<module name="NonEmptyAtclauseDescription"/>

<!--
Checks that one blank line before the block tag if it is present in Javadoc.
See: https://checkstyle.org/config_javadoc.html#RequireEmptyLineBeforeBlockTagGroup
-->
<module name="RequireEmptyLineBeforeBlockTagGroup"/>

<!--
Checks that a Javadoc block can fit in a single line and doesn't contain block tags.
See: https://checkstyle.org/config_javadoc.html#SingleLineJavadoc
-->
<module name="SingleLineJavadoc">
<property name="ignoredTags" value="@inheritDoc, @see"/>
</module>
</module>
</module>
@@ -88,12 +88,12 @@

<!-- Plugins versions -->
<apache.rat.plugin.version>0.13</apache.rat.plugin.version>
<checkstyle.puppycrawl.version>8.37</checkstyle.puppycrawl.version>
<checkstyle.puppycrawl.version>8.41.1</checkstyle.puppycrawl.version>
<launch.maven.plugin.version>1.7.25</launch.maven.plugin.version>
<maven.antrun.plugin.version>3.0.0</maven.antrun.plugin.version>
<maven.assembly.plugin.version>3.2.0</maven.assembly.plugin.version>
<maven.build-helper.plugin.version>3.2.0</maven.build-helper.plugin.version>
<maven.checkstyle.plugin.version>3.1.1</maven.checkstyle.plugin.version>
<maven.checkstyle.plugin.version>3.1.2</maven.checkstyle.plugin.version>
<maven.compiler.plugin.version>3.8.1</maven.compiler.plugin.version>
<maven.deploy.plugin.version>2.8.2</maven.deploy.plugin.version>
<maven.failsafe.plugin.version>3.0.0-M5</maven.failsafe.plugin.version>
@@ -709,6 +709,25 @@
</plugins>
</build>
</profile>

<!--
Profile to enable Javadoc style checks for public API.
-->
<profile>
<id>javadoc-public-api</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<configuration>
<configLocation>${project.basedir}/check-rules/checkstyle-public-api-javadoc.xml</configLocation>
<suppressionsLocation>${project.basedir}/check-rules/checkstyle-disabled-modules.xml</suppressionsLocation>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>

<build>

0 comments on commit 66def97

Please sign in to comment.