Note: The code samples discussed in this post are available at http://www.github.com/bradleyross/tutorials while the documentation can be found at http://bradleyross.github.io/tutorials. This project uses Maven. Although you don’t have to use Maven, the comments in the pom.xml and other configuration files provide a great deal of useful information.
As I mentioned in a previous post1, documentation is required in order to understand and debug the code. The Javadoc tool from Oracle provides a means of documenting Java code with the software development software itself carrying out the bulk of the effort.2 Meanwhile, the Maven pom.xml file provides a mean of providing additional information about the project in a computer readable manner.
- By processing the source code, it can generate a document that lists all of the classes in a project, including descriptions of the methods, fields, and constructors. Since it generates this information from the source code, it will always be up to date.
- It provides a method for the programmer to insert additional information into the document by reading specially formatted comments in the code.
- The Javadoc can contain the complete source code, with links from the detailed descriptions of the fields, constructors, and methods taking the user to their location in the source code.
- It is possible to link the Javadocs for libraries used by the project to the Javadocs for the project itself. This can make it
much easier to review the code.
- Using Maven and Javadocs together allow you to get a great deal of useful documentation for little effort. When the Agile Manifesto4 states Working software over comprehensive documentation, this is because of the Law of Diminishing Returns5. Spending too much time on documentation is wasteful, but not documenting at all will cause major problems later.
Like other Maven plugins, the Javadoc plugin has a number of conventions concerning where the files should be placed.6 These conventions will be discussed in terms of the
- Each Maven module should be located in it’s own directory on the server containing the documentation, and the Javadoc should be contained in the subdirectory
apidocsfor that directory. The main directory for the module is then placed in the pom.xml file using the tag url. For the tutorials-common module, the URL for the module documentation is http://bradleyross.github.io/tutorials/tutorials-common/ while the URL for the Javadocs is http://bradleyross.github.io/tutorials/tutorials-common/apidocs/.
- The modifications to the pom.xml file can be placed in either the module for which the Javadocs are being generated or in the parent module. I placed them in the parent module for simplicity.
- The overview for the module goes in the file src/main/javadoc/overview.html.
- ↑ 1. Bradley Ross, World’s Best Debugging Tool, https://bradleyaross.wordpress.com/2016/04/26/worlds-best-debugging-tool/
- ↑ 2. Oracle, Javadoc FAQ, http://www.oracle.com/technetwork/java/javase/documentation/index-137483.html
- 3. Bradley Ross, Javadoc for tutorials-common module in tutorials project, http://bradleyross.github.io/tutrials/tutorials-common/apidocs/
- ↑ 4. Agile Manifesto, http://www.agilemanifesto.org
- ↑ 5. Wikipedia, Law of Diminishing Returns, https://en.wikipedia.org/wiki/Diminishing_returns.
- ↑ 6. Apache Software Foundation, Documentation for Maven Javadoc Plugin, https://maven.apache.org/plugins/maven-javadoc-plugin/
- ↑ 7. Bradley Ross, Tutorials package on GitHub, http://www.github.com/bradleyross/tutorials.
- ↑ 8. Bradley Ross, Documentation for tutorials package on GitHub, http://bradleyross.github.io/tutorials/.