140 likes | 266 Views
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
E N D
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.
Comparison • 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)