Description

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

Properties

Examples

To configure the check:

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

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

directory
`-- Example1.java
        

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

// violation 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 package.html file in same directory:

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

public class Example2 { } // ok, package.html file is present in directory

To configure the check to only check .properties files for a package documentation file:

<module name="Checker">
  <module name="JavadocPackage">
    <property name="fileExtensions" value="properties"/>
  </module>
</module>

Directory structure with only a .properties file and no package-info.java:

directory
|-- Example4.java
`-- example.properties
        

Since fileExtensions is set to properties, the .java file is ignored, and the .properties file is checked instead - triggering a violation since no package-info.java is present:

public class Example4 { } // ok, .java file is not checked

Use Cases

To configure the check with allowLegacy set to true when both package-info.java and package.html exist in the same directory:

<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:

directory
|-- UseCase1.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.

// violation first line 'Legacy package.html file should be removed'
public class UseCase1 { }

Example of Usage

• Sun Style
• Checkstyle Style
• Documentation Comments Style

Violation Messages

• javadoc.legacyPackageHtml
• javadoc.packageInfo

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

Fully Qualified Name

com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocPackageCheck

Use this fully qualified class name in configuration when an exact class reference is required.

Parent Module

Checker