Overview

The Maven APIdoc plugin is a simple report generator containing the output of the Javadoc tool. On the one hand this allows to pinpoint problems in the Javadoc documentation to resolve. On the other hand it gives a report on the quality of the Javadoc comments of a project.

Currently the configuration of the tool is very limited. The standard doclet is run and only additional parameters set in the configuration of the maven-javadoc-plugin are used.

For details on configuration options please refer to apidoc:apidoc-report documentation.

Getting started

Adding the report to your Maven configuration is very simple. Just add the following lines to your reporting/plugins:

<plugin>
  <groupId>de.smartics.maven.plugin</groupId>
  <artifactId>apidoc-maven-plugin</artifactId>
</plugin>

Please note that the artifacts of this project are currently not available on the Maven Central Repository. If you want to integrate this plugin into your Maven build, please refer to Accessing Artifacts.

Best Practices

This list gives some tips about documenting the API.

• Classes
• Methods
• Getter and Setter
• Private Methods
• Test Methods
• Serialization

On the References Page we list interesting readings on API documentation.

Do we always follow all the rules given in the best practices? Honestly: no. It often depends on the expected life-time of the code (where unfortunately one can easily be mistaken). If the code is only for temporary use, it is a small tool for internal use, or it is application code called by noone, we are less strict on our comments. If we write a library we follow all those practices and consider it to be a bug if we fail to do so in a particular spot.

Cool Tools

We provide references to cool tools around API documentation.

• Javadoc
• Static Analyzers
• Taglets
• UmlGraph

Do we always use all these tools? Yes. Although we use the Taglets library less than we could but are planning to use it more aggressively in the future.