1 / 14

Advanced Javadoc Features and Limitations Explored by Wes Toland

This presentation by Wes Toland dives deep into the advanced features and limitations of Javadoc. It covers extensions such as Taglets and Doclets, illustrating how developers can enhance Javadoc functionality. The session highlights standard tags used for commenting, examples of implementing custom Taglets, and various Doclet tools. Key limitations of Javadoc compared to Doxygen, including HTML embedding issues and API referencing challenges, are also discussed. Attendees will gain insights into customizing Javadoc and understanding its role in Java documentation.

lazaro
Télécharger la présentation

Advanced Javadoc Features and Limitations Explored by Wes Toland

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  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. /** <p>This is a <b>doc</b> 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. 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

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

More Related