Javadoc Advanced Features Limitations Presented By Wes Toland

Javadoc: Advanced Features & Limitations Presented By: Wes Toland

Outline o Extensions n n o o Taglets Doclets Limitations Javadoc vs. Doxygen

Extensions o o 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: n n Taglets Doclets

Taglets o o 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 o 2 types of Taglets: n n n 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 # set. Bounds(int, int )} */ @deprecated is a block tag {@link} is an inline tag

Taglets o Default block tags: n n n @author @deprecated @exception @param @return @see @serial. Data @serial. Field @since @throws @version o Default inline tags: n n n n {@code} {@doc. Root} {@inherit. Doc} {@linkplain} {@literal} {@value}

Taglets o o Developers can add tags to Javadoc documentation by implementing a Taglet class Once the class is implemented, compile it: > export JDKHOME=/home/toland/jdk 5. 0 > cd /home/toland/taglets > javac -classpath $JDKHOME/lib/tools. jar To. Do. Taglet. java q Now you can document java source code that uses the implemented taglet: > javadoc -tagletpath /home/toland/taglets -taglet To. Do. Taglet -d /home/toland/www -sourcepath /home/toland/src Javadoc. Demo. java

Doclets o o o 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 o Popular Doclet tools: n n 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 o 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 o 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 o o 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 crossreference links for any given class/method/variable assuming the classpath is set correctly.

Comparison o Supported programming languages: n n o o Javadoc comments must be directly before the object being copied, Doxygen is configurable. Link generation n n o Javadoc: Java only Doxygen: C/C++, Java, Python, PHP Java requires explicit object link path Doxygen requires an object name and will determine link path Source code display n n Java cannot display source code anywhere in the API documentation Doxygen can display AND format source code in documentation

Comparison o Both support detailed and summarized API views n o o 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)