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 * </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 JavadocDemo extends Applet {

}

Features: Comment Format 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 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/srcjavadoc –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: http://java.sun.com/j2se/1.5.0/docs/api/ 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.