Javadoc Standards

Owned by Former user (Deleted)
Last updated: Apr 07, 2009Version comment

Javadoc

Javadoc is a function of the Java Development Kit that allows programmers to integrate documentation and other information into the source code. This conveniently allows developers to document a program as they work, rather than leave all of the doc tasks until the end of the process. After a program is compiled, you can optionally generate a collection of Javadoc-based HTML pages by using the JDK's javadoc function to pull all of the Javadoc comments out of the files you specify, along with member names so that readers know which class or method the comments belong to. The resulting Web site looks like this.

This is by far the easiest way to create API documentation; you write it as you go, and produce the documentation deliverable when you're done coding.

Implementation

Javadoc is designed to provide other programmers with information about a program's extensibility, interactivity, and outward-facing functionality. Therefore it will only work with public and protected classes and methods (there is a way to generate Javadoc for private members, but this should not be necessary for Pentaho software).

It's possible to extend Javadoc's functionality through handlers called Doclets, though there is no conceivable reason why you would do this for Pentaho-related development.

There are many Javadoc tags. If you'd like to see a complete listing, consult Sun's JDK Javadoc page. For Pentaho software development, concentrate on using these tags, where appropriate:

Javadoc tag

Purpose

@author

Identifies the programmer who wrote the code. This can be used in multiple lines for the author's name and various forms of contact information.

@param parameter-name

This tag explains the parameters a particular class or method will accept or expect. Each parameter must be specified individually by name.

@return

Explains what data a method returns.

@throws fully-qualified-class-name

Explains the class that throws the exception object, and then explains under what conditions this exception can happen.

@version

Specifies the release version number of the software that contains this class.

{@link}

Inserts an in-line link with visible text label that points to the documentation for the specified package, class or member name of a referenced class.

All of the public and protected classes and methods in all Pentaho software should have sufficient Javadoc. Ideally, an extension developer should be able to read Pentaho Javadoc and gain a decent understanding of what each member does and returns.

Example

The following class shows what happens when you put Javadoc comments into a program (and if you actually run it, it prints an inspiring message):

import java.util.*;
/** This class prints the following message: Brevity is the soul of wit,
* a phrase made famous by {@link <a href="http://en.wikipedia.org/Shakespeare">William Shakespeare</a>}.
* By the way... multi-line Javadoc comments
* use a carriage return for EOLN (just press Enter), and require
* an asterisk at the beginning of each additional
* line.
* @author Jem Matzan
* @author jmatzan@nospam4meplzpentaho.com
* @version 2.1.0-RC1
*/
public class DocMessage {
    /** Main method prints the message.
    * @param args Takes an array of String arguments.
    * @throws exceptions No exceptions thrown.
    * @return Nothing!! It's a frickin' void!
    */
    public static void main(String[] args) {
        System.out.print("Brevity is the soul of wit.");
    }
}