A Java tool I would like to have

Dave Yost
3/25/98

javacomment - The Java Documentation Comment Generator

Adds pro forma doc comments to and corrects exsiting doc comments in Java source files.

SYNOPSIS

javacomment [ options ] source.java*

DESCRIPTION

Javacomment parses the declarations and documentation comments in each given Java source file and produces for each one a new source file with correct doc comments for the class and for all fields and methods. Where there was no doc comment, a pro forma one is inserted, and where there was one, it is corrected and fleshed out if necessary.

Javacomment inserts the flag string NEEDSWORK wherever it creates or detects a void that the programmer must fill with descriptive text. Incorrect tag lines (e.g. incorrect argument information) javacomment replaces or deems extraneous are retained with the flag string prepended.

The old version of the file is moved into a subdirectory called old. If you want more information about what javacomment changed, use a file comparator.

OPTIONS

You can use an argument beginning with the character '@' to specify a file containing additional arguments, one argument per line. These arguments are inserted into the command line at the position of the '@<filename>' argument.

Javacomment Options

-author string
Specifies the text for the @author tag.
-flag string
Insert string wherever javacomment creates or detects a void that the programmer must fill with descriptive text. Default is "NEEDSWORK".
-nofields
Don't add doc comments for fields, only methods.
-nosince
Don't include the @since tag.
-old directoryname
Move the original versions of all target files to directoryname instead of to old. Use "" if you don't want to retain the old version.
-publiconly
Add doc comments only to the class and the public methods, but still correct others encountered.
-since string
Insert string after every @since tag. Default is "".

EXAMPLES

In the following example, only the contains() method had a doc comment (which was incorrect). (Only some methods are shown.)

javacomment -author "Josh Bloch" -since JDK1.2 ArrayList.java

/**
 * ArrayList class NEEDSWORK
 *
 * @author  Josh Bloch
 * @since JDK1.2
 */
public class ArrayList extends AbstractList
        implements List, Cloneable, java.io.Serializable {

    /**
     * NEEDSWORK
     * @since JDK1.2
     */
    private Object elementData[];

    /**
     * Returns true if this ArrayList contains the specified element.
     *
     * @param elem NEEDSWORK
     * NEEDSWORK @param o element whose presence in this List is to be tested.
     * @since JDK1.2
     */
    public boolean contains(Object elem) {
        return indexOf(elem, 0) >= 0;
    }

    /**
     * NEEDSWORK
     *
     * @param index NEEDSWORK
     * @param element NEEDSWORK
     * @return NEEDSWORK
     * @exception ArrayIndexOutOfBoundsException NEEDSWORK
     * @exception IllegalArgumentException NEEDSWORK
     * @since JDK1.2
     */
    public Object set(int index, Object element) {
        if (index >= elementCount)
            throw new ArrayIndexOutOfBoundsException(index);

        Object oldValue = elementData[index];
        elementData[index] = element;
        return oldValue;
    }
}