The Basics of Javadoc Presented By: Wes Toland

Outline  Overview  Background  Environment  Features Javadoc Comment Format Javadoc Program HTML API Documentation  Main Uses  DEMO  Comparison with Doxygen

Overview  Generate Java API documentation in HTML format (by default).  Extract important information from: Classes & Inner classes Interfaces Constructors Methods Fields  API documentation can be generated for: Entire packages Individual source files

Background  Javadoc is included in Sun Microsystem’s Java 2 Software Development Kit.  Javadoc 5 is included in the J2SE Platform Development Kit Standard Edition 5 (JDK5).  Javadoc has been supported since JDK1.1.

Environment  Due to the Java Virtual Machine (JVM), the Java Development Kit (JDK) and Runtime Environment (JRE) are supported on all platforms.  java.sun.com provides the JDK5 download, platform-specific installation instructions, and user manuals for each component of the development kit: javac (compiler) jar (archiver/packager) javadoc (API documentation tool) jdb (debugger)

Features: Comment Format  Java developers follow a certain format when creating Javadoc comments. /** * JavadocDemo * An applet with Javadoc comments Wes Toland $Id: Examples, v /02/24 01:02:53 Exp $ java.applet.Applet java.swing.JApplet */ public class JavadocDemo extends Applet { }

Features: Comment Format  Javadoc comments begin with a \** and end with */  Javadoc tags begin  Javadoc comments should be placed above the class/method/interface being documented  Additional HTML formatting can be specified

Features: Javadoc Program  Once a package or set of Java files have been commented, run the Javadoc utility either from the command line or from IDE.  javadoc –d /home/toland/www –sourcepath /home/toland/src \ -subpackages java –exclude java.net;java.lang  cd /home/toland/src  javadoc –d /home/toland/www java.awt java.awt.event  javadoc –d /home/toland/www –sourcepath /home/toland/src1;\ /home/toland/src2 java.awt java.awt.event Example 1: Example 2: Example 3:

Features: HTML API Format  Javadoc program generates nicely-formatted HTML API documentation.  HTML documentation is organized across the following types of files: Basic content files Cross-reference pages Support files HTML frames  Basic content files contain the most important information for each: Class Interface Package

Features: HTML API Format Class Hierarchy:

Features: HTML API Format Class Documentation:

Features: HTML API Format Quick-Reference API:

Main Uses  Development Quick Reference APIs are useful for internal development Developers can quickly see what methods are available for use See:  Commercial Releases Detailed APIs are provided in addition to Quick Reference APIs This is useful for clients to see if the developers met the specs

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.