Good Javadoc use

Javadoc is a tool that you have in your %JAVA_HOME%\bin (Windows) or $JAVA_HOME/bin (UNIX) directory. It is being used to extract API documentation from your Java source code, into HTML.

Most IDEs fully support Javadoc. They assist the developer in writing, displaying and generating the Javadoc documentation. Javadoc is part of the development lifecycle. Good and up-to-date Javadoc is a sign of a healthy project.

API Users

The worst thing an API user can do is to ignore Javadoc. Having an easily accessible, local copy of the Javadoc for the library you are working with (Spring, Hibernate, Lucene etc) is the only way to work efficiently. Vast amounts of time have been put into compiling quality documentation for these libraries. Not using it will only slow you down.

Development Teams

One of the worst Netbeans feature is that it allows you to collapse all comments and even set this as the default behavior when opening a source file. Team members, working in the same piece of code, can no longer see the documentation written by other developers.
I actually had a developer asking me about what one of my methods did. For a moment I was confused and asked him whether I had written poor documentation. He then told me that he didn’t know that there was any Javadoc for that method. I don’t (want to) know whether Javadoc hiding is a feature of Netbeans or is a plugin, but that was definitely one of the most ineffective behaviors I’ve seen in a development team.

API designers

Writing good Javadoc involves many things which are documented by SUN. The general idea is that you don’t want to expose the implementation of the method through the documentation. API users will not care how you do it, but only what (and maybe why) you do.
So the following comment is bad:

/** 
 * This method uses StringBuffer to merge the name with surname and return
 * the person's full name
 */
 public String getFullName() {

A better version is:

/** 
 * Returns the full name of the Person. Will return "Nick Cave" if
 * firstname is "Nick" and lastname is "Cave".
 *
 * @return      the full name of the Person
 */
 public String getFullName() {

Conclusion

We (Java developers) are very lucky that documentation is so tightly integrated with the language. Not using it though, takes all this goodness away.

3 Responses to “Good Javadoc use”

  1. Sakisk Says:

    Αν και microsoft developer, ο ίδιος, πάντα μου άρεσε το πόσο καλά δομημένο και λειτουργικό εργαλείο είναι το javadoc. Είναι κρίμα που δεν διαθέτουμε λίγο παραπάνω χρόνο να γράφουμε καλό documentation με τον κώδικά μας…
    Για τους microsoftαδες υπάρχει το Sandcastle (νομίζω της microsoft)
    http://www.sandcastledocs.com/Wiki%20Pages/Home.aspx
    και το open source Ndoc
    http://ndoc.sourceforge.net/
    Αυτά έχω χρησιμοποιήσει και είναι αρκετά καλά.

  2. John Kostaras Says:

    If you want to have a nice Javadoc API as the one of JDK, ie. with the packages on the upper left, all classes on lower left etc. then I use the following script to create my Javadoc:

    rem This will create the API for  application
    rem YOU MUST EDIT THE SETTINGS IN THIS FILE TO MATCH YOUR CONFIGURATION
    
    rem Save old classpath
    set OLD_CP=%CLASSPATH%
    
    rem Output directory
    rem CHANGE THIS TO THE FOLDER YOU WISH TO CREATE THE API DOCUMENTATION
    set OUTPUT_FOLDER=..\doc\api
    
    rem Application top-level directory
    rem CHANGE THIS TO MATCH YOUR CONFIGURATION
    set APP_HOME=.
    
    rem CLASSPATH 
    set CLASSPATH=.;%APP_HOME%;
    
    javadoc -d "%OUTPUT_FOLDER%" -windowtitle " - Copyright @ 2006-2007" -doctitle " API Specification" -bottom  "©, " -classpath %classpath%  -package -author -version @packages.txt
    
    rem Restore old classpath
    set CLASSPATH=%OLD_CP%

    Save the above to a .bat or .cmd or .sh file in the top directory of your application, e.g. where folder app is, if app is the name of the root package of your application.

    You also need a packages.txt file in the same directory which contains the names of all the packages of your application one per line, i.e. in the form:
    app
    app.db
    app.io
    app.io.ui
    app.help
    etc.

    Inside each package you must have a package.html file with the following ingredients:

    Application package
    
    bla bla bla description of the package bla bla bla

    Here you modify the title and the body. You must add a package.html to every package and sub-package of your application.

    I know it is a lot of work, but Voila.

  3. cherouvim Says:

    Yep, package.html is nice.

    Thanks!