1 / 15

The Basics of Javadoc

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

hammer
Download Presentation

The Basics of Javadoc

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. The Basics of Javadoc Presented By: Wes Toland

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

  3. 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

  4. 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.

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

  6. 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 { }

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

  8. 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. 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 java.awt.event Example 3: • javadoc –d /home/toland/www –sourcepath /home/toland/src1;\ /home/toland/src2 java.awt java.awt.event

  9. 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

  10. Features: HTML API Format Class Hierarchy:

  11. Features: HTML API Format Class Documentation:

  12. Features: HTML API Format Quick-Reference API:

  13. 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

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

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

More Related