Transcript JavaDoc - University of Delaware

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