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: /** As of JDK 1.1, replaced by #setBounds(int,int,int,int)} is a block tag is an inline tag

Taglets  Default  Default inline tags:

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. /** This is a doc comment. 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:

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 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

 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)