The Basics of Javadoc Presented By Wes Toland

The Basics of Javadoc Presented By: Wes Toland

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

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

Background o o o Javadoc is included in Sun Microsystem’s Java 2 Software Development Kit. Javadoc 5 is included in the J 2 SE Platform Development Kit Standard Edition 5 (JDK 5). Javadoc has been supported since JDK 1. 1.

Environment o o 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 JDK 5 download, platform-specific installation instructions, and user manuals for each component of the development kit: n n javac (compiler) jar (archiver/packager) javadoc (API documentation tool) jdb (debugger)

Features: Comment Format o Java developers follow a certain format when creating Javadoc comments. /** * Javadoc. Demo * </p>An applet with Javadoc comments * @author Wes Toland * @version $Id: Examples, v 1. 0 2007/02/24 01: 02: 53 Exp $ * @see java. applet. Applet * @see java. swing. JApplet */ public class Javadoc. Demo extends Applet { }

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

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

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

Features: HTML API Format Class Hierarchy:

Features: HTML API Format Class Documentation:

Features: HTML API Format Quick-Reference API:

Main Uses o Development n n n o Quick Reference APIs are useful for internal development Developers can quickly see what methods are available for use See: http: //java. sun. com/j 2 se/1. 5. 0/docs/api/ Commercial Releases n n Detailed APIs are provided in addition to Quick Reference APIs This is useful for clients to see if the developers met the specs

Comparison o Supported programming languages: n n o o Javadoc comments must be directly before the object being copied, Doxygen is configurable. Link generation n n o Javadoc: Java only Doxygen: C/C++, Java, Python, PHP Java requires explicit object link path Doxygen requires an object name and will determine link path Source code display n n Java cannot display source code anywhere in the API documentation Doxygen can display AND format source code in documentation

Comparison o Both support detailed and summarized API views n However, Doxygen can generate 2 separate documents where Javadoc includes both views in the same documentation.