Javadoc: Advanced Features & Limitations

Presented By: Wes Toland

Outline

Extensions Taglets Doclets

Limitations Javadoc vs. Doxygen

Extensions

Most Java developers are happy with the default functionality of javadoc

Sun also provided the ability for developers to extend the functionality of javadoc via: Taglets Doclets

Taglets

Javadoc supports almost 20 “tags” that are used to document the details of Java classes, methods, etc…

JDK also provides a taglet interface that developers can implement in order to support any additional flags they desire.

Taglets

2 types of Taglets: Block tags: Must begin at beginning of

line Inline tags: Can be placed anywhere in

javadoc comments Example:

/** * @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)} */

@deprecated is a block tag{@link} is an inline tag

Taglets Default block tags:

@author @deprecated @exception @param @return @see @serial @serialData @serialField @since @throws @version

Default inline tags: {@code} {@docRoot} {@inheritDoc} {@link} {@linkplain} {@literal} {@value}

Taglets Developers can add tags to Javadoc

documentation by implementing a Taglet class

Once the class is implemented, compile it:> export JDKHOME=/home/toland/jdk5.0> cd /home/toland/taglets> javac -classpath $JDKHOME/lib/tools.jar ToDoTaglet.java

Now you can document java source code that uses the implemented taglet:

> javadoc -tagletpath /home/toland/taglets -taglet ToDoTaglet \ -d /home/toland/www -sourcepath /home/toland/src \ JavadocDemo.java

Doclets By default, Javadoc generates the Java API

Documentation in a specific HTML format using the Standard Doclet.

Developers can customize the content and format of the API Documentation by either modifying the Standard Doclet or implementing a new Doclet.

The MIF Doclet has become a popular format, and is often used to generate API documentation in a PDF format.

Doclets Popular Doclet tools:

Standard Doclet – default HTML API documentation generation.

MIF Doclet – generate API documentation in MIF (Maker Interchange Format). Can also convert HTML files to MIF and PDF.

Doc Check Doclet – extension to Javadoc tool. Used to review documentation comments and report empty comments and other ommissions.

Exclude Doclet – a javadoc wrapper program that allows user to exclude any specified public or protected classes.

Limitations Many Java developers hate embedding HTML

tags within Javadoc comments in order to obtain a certain format of documentation output.

/** <p>This is a <b>doc</b> comment. * @see java.lang.Object */

Limitations Doxygen supports class hierarchy graphs by default.

This feature could be added to Javadoc by extending the Standard Doclet or creating a new one, but this would require a large amount of effort.

Figure: An example of a Doxygen class hierarchy graph courtesy of:http://www-scf.usc.edu/~peterchd/doxygen/

Limitations In order to reference Javadoc APIs outside of the

class being documented, the full path of the HTML files being referenced must be specified using the inline {@link} tag.

Doxygen can automatically generate the API cross-reference links for any given class/method/variable assuming the classpath is set correctly.

Supported programming languages: Javadoc: Java only Doxygen: C/C++, Java, Python, PHP

Javadoc comments must be directly before the object being copied, Doxygen is configurable.

Link generation Java requires explicit object link path Doxygen requires an object name and will determine link

path Source code display

Java cannot display source code anywhere in the API documentation

Doxygen can display AND format source code in documentation

Comparison

Comparison Both support detailed and summarized API views

However, Doxygen can generate 2 separate documents where Javadoc includes both views in the same documentation.

Doxygen supports modules/grouping, Javadoc does not

Doxygen supports structural commands, Javadoc does not (but this feature is not very desirable)