Javadoc – Generating Automated documentation

TIP: References Quick List

Additional Info:

Whether making a project that we use as a dependency in another project, or if other teams / developers may use our jar as a dependency in their own project(s), making the Javadoc comments from our source code available as a separate javadoc jar can be of great help.

Some IDEs, such as IntelliJ may also automatically download source and Javadoc jars for dependencies, if available, making them available when you hover over a method as popup documentation.
You may also need to publish the Javadoc documentation to a site, so other developers can view it in a browser. Many of the prior posts already linked to online Javadocs.
Even within the same project, where the source code is available, you may find use of the Javadoc documentation. For example, it contains information about where inherited methods come from (which parent in the object hierarchy structure). We will be looking back at the java101 project Javadoc as we start talking more about Objects in a future post.

Adding this as a separate output (artifact) of the build is very easy/simple, too.

Updating the pom.xml

The Apache Maven Javadoc Plugin will generate it for us. We just have to add it to the build’s plugins configuration section.

<plugin>
  <!-- https://maven.apache.org/plugins/maven-javadoc-plugin/ -->
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.5.0</version>
  <inherited>true</inherited>
  <executions>
    <execution>
      <id>attach-javadocs</id>
      <goals>
        <goal>jar</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <failOnError>true</failOnError>
    <failOnWarnings>true</failOnWarnings>
  </configuration>
</plugin>

The only updates I made to the configuration section is to fail on errors / warnings. This is another build breaker to ensure that documentation work is done as we go, rather than deciding it is needed later-on and then having a lot of catch-up work to do at that point.

Some IDEs may also understand Maven poms well enough to provide developers a link to the plugin’s site. However, I went ahead and included a link in a comment, just in case, as some folks edit their code outside of one of those IDEs.

Maven Build Run

Based upon the execution section in the pom.xml update above, we should expect a portion of our build to be identified as attach-javadocs to run.

[INFO] --- javadoc:3.5.0:jar (attach-javadocs) @ java101 ---
[INFO] No previous run data found, generating javadoc.
[INFO] Building jar: ...\java101\target\java101-0.1-SNAPSHOT-javadoc.jar

That new jar is part of the build artifacts. If we decide to invoke the deploy phase in the future, it will be published to Maven Central / whatever artifact repository we use.

Examining Javadoc Locally

In addition to the jar, we can also see them by looking at java101/target/apidocs/index.html. In IntelliJ, if we Right Click on the index.hmtl -> Open In -> Browser -> Choose your favorite browser. Then the index.html page should be displayed in that browser.

Commit

Remember, commit in small increments. Now is a good time to do so.

Coding Chica