For many Java projects, Javadoc comments are an important source of low-level technical documentation. There are even tools, such as UmlGraph, that let you produce Javadoc with embedded UML diagrams to give you a better picture of how the classes fit together in the application. This sort of technical documentation has the advantage of being cheap to produce, accurate and always up-to-date.

Jenkins can integrate Javadoc API documentation directly into the Jenkins website. This way, everyone can find the latest Javadoc easily, in a well known place. Often, this sort of task is performed in a separate build job, but for simplicity we are going to add another build step to the gameoflife-default build job to generate and display Javadoc documention for the Game of Life API.

Start off by going into the “gameoflife-default” configuration screen again. Click on “Add build step”, and add a new build step to “Invoke top level Maven targets” (see Figure 2.25, “Adding a new build step and report to generate Javadoc”). In the Goals field, place javadoc:javadoc—this will tell Maven to generate the Javadoc documentation.

Now go to the “Post-build Action” and tick the “Publish Javadoc” checkbox. This project is a multimodule project, so a separate subdirectory is generated for each module (core, services, web and so forth). For this example, we are interested in displaying the documentation for the core module. In the Javadoc directory field, enter gameoflife-core/target/site/apidocs—this is where Maven will place the Javadocs it generates for the core module. Jenkins may display an error message saying that this directory doesn’t exist at first. Jenkins is correct—this directory won’t exist until we run the javadoc:javadoc goal, but since we haven’t run this command yet we can safely ignore the message at this stage.

If you tick “Retain Javadoc for each successful build”, Jenkins will also keep track of the Javadocs for previous builds—not always useful, but it can come in handy at times.

Now trigger a build manually. You can do this either from the build job’s home page (using the Build Now link), or directly from the server home page. Once the build is finished, open the build job summary page. You should now see a Javadoc link featuring prominently on the screen—this link will open the latest version of the Javadoc documentation (see Figure 2.26, “Jenkins will add a Javadoc link to your build results”). You will also see this link on the build details page, where it will point to the Javadoc for that particular build, if you have asked Jenkins to store Javadoc for each build.