On Java Development

All things related to Java development, from the perspective of a caveman.

Using Java’s Javadoc Tool

without comments

Introduction

This post shows how to use Java’s Javadoc tool to create HTML pages that present information derived from Javadoc annotations.

 

Java Documentation

Everyone’s seen web pages like that below. They’re used to present documentation for Java class file including the packages in which they reside.
JavadocHome

 
When you select on one of the hyperlinks for a class, a page like the one below is presented.
JavadocDateTimeHelper

 

Creating Java Documentation

To create web pages like this, a little preparation is need. First, create a directory into which the generated HTML is to be placed. As shown below, the directory C:\…\JavaDocs\BaseProject has been created to hold the Javadocs for the project called baseproject.
JavadocHTMLDir

Next, start a cmd window and execute the Javadoc program that resides in C:\Progra~1\Java\jdk1.6.0_37\bin. There are three parameters that are provided:

  • -d C:\Desk\JavaDocs\BaseProject : This specifies the directory presented above that will contain the generated documentation.
  • -sourcepath C:\Desk\AppDevSpring\BaseProject\baseproject\src\main\java : This specifies the directory where the scanning should begin.
  • -subpackages com.mig.baseproject.utilities : This specifies that Javadoc should scan the named subpackage.

The entire command structure looks like this;
C:\Progra~1\Java\jdk1.6.0_37\bin\javadoc -d C:\Desk\JavaDocs\BaseProject -sourcepath C:\Desk\AppDevSpring\BaseProject\baseproject\src\main\java -subpackages com.mig.baseproject.utilities

When executed the following output similar to that shown below is produced.

 

Displaying the Java Documentation

The generated output is placed in the directory created for this purpose, described above.

JavadocGeneratedHTMLDir

The structure reflects the utilities directory and all sub-directories as instructed by Javadoc’s subpackages parameter:
-subpackages com.mig.baseproject.utilities

To start at the beginning index page, double-click on the file index.html.

That’s it! Of course, the only caveat to all this is that the documentation produced is only as good as the information given on the associated Javadoc annotations of each class. So, for more information about Javadoc and annotations, see this link.

Written by admin

January 14th, 2015 at 6:33 am

Posted in Java Utilities

Leave a Reply

You must be logged in to post a comment.