JavaDoc Coverage Maven Plugin

A Maven plugin to generate JavaDoc coverage reports. It parses the java source files and checks the percentage of the Java code covered by JavaDoc documentation, including:

• packages (Java 9 modules not supported yet)
• classes, inner classes, interfaces and enums
• class attributes
• methods, parameters, exceptions and return value.

A sample coverage report is available here.

Current IDEs warns about missing JavaDoc tags and documentation, allowing you to individually fix the issues. Similar to code coverage tools, this plugin provides a way to get a summarized overview of your project's documentation coverage. It provides a Doclet to be used with the JavaDoc Tool and the maven-javadoc-plugin to show JavaDoc documentation coverage of your project.

Building the Plugin

The plugin is a Java Maven project which can be built directly from any IDE or using the following maven command:

mvn clean install

The command builds the plugin and install it at your local maven repository.

How to use the Plugin

To generate the regular JavaDoc HTML files and the coverage report, you have to include two configurations for the maven-javadoc-plugin inside your project's pom.xml file, as exemplified below.

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.10.4</version>
            <executions>
                <!-- Exports JavaDocs to regular HTML files -->
                <execution>
                    <id>javadoc-html</id>
                    <phase>package</phase>
                    <goals>
                        <goal>javadoc</goal>
                    </goals>
                </execution>

                <!-- Generates the JavaDoc coverage report -->
                <execution>
                    <id>javadoc-coverage</id>
                    <phase>package</phase>
                    <goals>
                        <goal>javadoc</goal>
                    </goals>
                    <configuration>
                        <doclet>com.manoelcampos.javadoc.coverage.CoverageDoclet</doclet>
                        <docletArtifact>
                            <groupId>com.manoelcampos</groupId>
                            <artifactId>javadoc-coverage</artifactId>
                            <version>1.0.0</version>
                        </docletArtifact>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    <plugins>
<build>

Now, to generate the regular JavaDocs in HTML and the documentation coverage report, you can execute the package goal in Maven, using your IDE or the command line inside your project root directory:

mvn clean package

After that, the documentation coverage report javadoc-coverage.html is generated into the default JavaDocs directory, usually at target/site/apidocs/.

There is a maven sample project where you can test the plugin. Just execute the command above inside the project's directory to see the results.

Excluding packages from the coverage report

If you want to ignore some packages from the coverage report, you can include a configuration for the javadoc-coverage plugin. The example below shows how to ignore the com.manoelcampos.sample2 package from coverage report for the sample-project, while covering all packages for generation of the regular JavaDoc HTML files.

The <excludePackageNames> tag is used for that purpose. It accepts a list of packages separated by : and also accepts wildcards such as *. For more details, check this link.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.4</version>
    <configuration>
        <encoding>UTF-8</encoding>
    </configuration>
    <executions>
        <!-- Exports JavaDocs to regular HTML files -->
        <execution>
            <id>javadoc-html</id>
            <phase>package</phase>
            <goals>
                <goal>javadoc</goal>
            </goals>
        </execution>

        <!-- Generates the JavaDoc coverage report -->
        <execution>
            <id>javadoc-coverage</id>
            <phase>package</phase>
            <goals>
                <goal>javadoc</goal>
            </goals>
            <configuration>
                <doclet>com.manoelcampos.javadoc.coverage.CoverageDoclet</doclet>
                <docletArtifact>
                    <groupId>com.manoelcampos</groupId>
                    <artifactId>javadoc-coverage</artifactId>
                    <version>1.0.0</version>
                </docletArtifact>
                <!-- Excludes packages from the coverage report. -->
                <excludePackageNames>com.manoelcampos.sample2</excludePackageNames>
            </configuration>
        </execution>
    </executions>
</plugin>