JavadocPackage

Since Checkstyle 5.0

Description

Checks that each Java package has a Javadoc file used for commenting. By default, it only allows a package-info.java file, but can be configured to allow a package.html file.

A violation will be reported if both files exist as this is not allowed by the Javadoc tool.

Properties

name	description	type	default value	since
allowLegacy	Allow legacy `package.html` file to be used.	boolean	`false`	5.0
fileExtensions	Specify the file extensions of the files to process.	String[]	`.java`	5.0

Examples

To configure the check:


<module name="Checker">
  <module name="JavadocPackage"/>
</module>

Directory structure with no package-info.java file in directory:

Example1.java

The following violation is raised in default when package-info.java file is missing from directory.


package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocpackage.nonlegacy;
/* violation on first line 'Missing package-info.java file' */
public class Example1 { }

To configure the check with allowlegacy set to true:


<module name="Checker">
  <module name="JavadocPackage">
    <property name="allowLegacy" value="true"/>
  </module>
</module>

Directory structure with with package.html file in same directory:

Example2.java

package.html

The legacy configuration (allowLegacy=true) allows the use of the legacy package.html file as an alternative to package-info.java removing violation


package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocpackage.legacy;
// OK as package.html file is present in directory
public class Example2 { }

To configure the check with allowlegacy set to true:


<module name="Checker">
  <module name="JavadocPackage">
    <property name="allowLegacy" value="true"/>
  </module>
</module>

Directory structure with both package-info.java and package.html file in same directory:

Example3.java

package.html

package-info.java

The legacy configuration (allowLegacy=true) allows the use of package.html files in place of package-info.java but still enforces that only one file (either package-info.java or package.html) exists in a package.


package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocpackage.legacywithboth;
/* violation on first line 'Legacy package.html file should be removed' */
public class Example3 { }

Example of Usage

Violation Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

Checker