1. Javadoc: Advanced Features & Limitations Presented By: Wes Toland

2. Outline  Extensions Taglets Doclets  Limitations  Javadoc vs. Doxygen

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

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

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

6. 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}

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

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

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

10. 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. * @see java.lang.Object */

11. 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/

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

13.  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

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