Jass - Documentation

JavaDoc Support

1 JavaDoc support

JavaDoc is a tool included in the JDK distribution for automatic HTML documentation generation. It supports special tags that describe entities like parameters, return values and exception. A JavaDoc generated documentation is quasi standard for Java APIs.

1.1 How Jass supports JavaDoc

Jass supports JavaDoc in a very easy way. If a formal comment is found in front of a method or a class, by default Jass adds special tags at the end of this comment that describe the pre- and postconditions or the class invariant. To generate the documentation you may run the javadoc with the Doclet provided in the jass distribution (when using Java < 1.4), or the special -tag options (javadoc 1.4). Have a look at the example.xml ant build-file to see how to do so.

Alternativly by giving the option -htmldoc you may instruct Jass to add plain HTML code. Option -nodoc disables the JavaDoc support.

1.2 An Example

JavaDoc would generate from the following source code ...

  
/**
 * This methods adds an object to the buffer.
 * @param o the object that should be added.
 */
public void add(Object o) {
    /** require [valid_object]    o != null; 
                [buffer_not_full] !full();    **/
    buffer[in % buffer.length] = o;
    in++;
    /** ensure Old.in == in - 1; **/
}

... the following HTML code:

add

public void add(Object o)

This methods adds an object to the buffer.

Parameters:

o - the object that should be added.

If the source code is passed through Jass the resulting HTML code looks like ...

add

public void add(Object o)

This methods adds an object to the buffer.

Requires:

valid_object: o!=null &&
buffer_not_full: !full()

Ensures:

Old.in==in-1

Parameters:

o - the object that should be added.