Intranet Journal
The online resource for intranet professionals
Running Javadoc on your code
Javadoc is basically just a command line utility that you use with arguments to specify on what classes or packages to run the tool, the output path for the
generated documentation, and any options.
That is,
Javadoc class1, class2,…classx destination –option1 –option2
Most likely you’ll have multiple classes or packages with the same destination and options on which to run Javadoc. To make your life easier, you can simply create a batch file with your Javadoc command and run that repeatedly without ever having to retype everything.
Most likely, you will want to include some options with your Javadoc command. There are quite a few of them and a complete reference can be found in the “Javadoc™-The Java API Generator” reference. I will discuss the few I found most beneficial to me by excerpting them from the reference I mention above and adding my additional comments, where appropriate.
-public
Shows only public
classes and members.
-protected
Shows only protected
and public classes and members. This is the default.
-package
Shows only package,
protected, and public classes and members.
-private
Show all classes and
members.
-verbose
The
ever-popular command line option that means more comments will be displayed in
the window as Javadoc runs.
-windowtitle
title
Specifies the title to
be placed in the HTML <title> tag. This appears in the window title and
in any browser bookmarks that someone creates for your documentation.
The options I found most useful, however were the –link and –linkoffline options. These allow you to create links to existing Javadoc-generated documentation for external referenced classes. For example, if you use one of the link options and you link directly to the Standard Java API on the Sun website, references to any of the standard classes (like String, Character, Collection, etc.) within your Javadoc documentation will automatically link to the API. This is a beautiful feature for the developer using your documentation because they can move seamlessly between your API and any others to which you linked.
-link extdocURL
This uses the URL you specify both at the time Javadoc runs and in the output documentation to create the external links. If the URL is on the World Wide Web, Javadoc must have a web connection in order to access the package-list at this location at the time it runs (Javadoc uses the package-list file of the external API to generate its links).
-linkoffline
extdocURL packagelistLoc
This option is a variation of –link and accomplishes the same external referencing. The differences here is that you specify a package-list location that is on your local machine. This allows you to overcome the constraint of your Javadoc having web access to the external URL at the time you generate the documentation. This is extremely useful if you are generating your Javadoc documentation from inside a firewall or proxy for instance.
Example
To tie this all together, let me give you a real world
example of a Javadoc command from the batch file I used on my most recent
application.
Javadoc Action.java
AddRecordTask.java AuthenticateTask.java DeleteRecordTask.java -public
-windowtitle "My Lovely Application-API" -d c:\www\apidocs\myapp -linkoffline
http://java.sun.com/j2se/1.4/docs/api/ /jdk1.3.1/docs/api
Here I run Javadoc on several class source files (I cut down the large list for brevity here), and invoke the –public, -windowtitle, and-linkoffline options.
By no means do I intend for this to be a definitive Javadoc guide. In fact, there are still features of this tool I do not understand because I haven’t had the opportunity to use them. However, it should at least give you an understanding of what the tool offers and how to get started. At the very least it should ease your awkwardness and “deer in the headlights feeling” the next time you’re faced with an experienced Java guru telling you to just set up the Javadoc for your application.