An Introduction to Javadoc Documentation

Summary

This reading provides a highl-level overview of the documentation system, called Javadoc that is included in the Java environment.

Introduction

The Javadoc documentation system is included within the Java software development environment. Extensive notes on this system may be found in How to Write Doc Comments for the Javadoc Tool. What follows are some comments to get you going.

javadoc Comments

Although the javadoc system includes a wide range of capabilities, the basic approach is reasonably straight forward:

• A javadoc comment starts with /** (note the two asterisks rather than one), and ends with */ (the same as any comment). Often, multi-line comments begin with an asterisk to show continuity of the comment. Altogether, Javadoc comments can be on one line or several lines:

     /** this Javadoc comment is on one line */
  
     /**
      * this Javadoc comment extends
      * over several lines.
      */
  

• A Javadoc comment can be placed immediately before
  • a class definition
  • an interface definition
  • a field
  • a constructor
  • a method

Javadoc comments in other locations are ignored, as are multiple Javadoc comments before classes, interfaces, etc.

Generating Documentation

In a general software development setting, a program Javadoc can be used to extract Javadoc information into a unified collection of Web pages.

Within Eclipse, you can generate Javadoc materials for a project, package, or class as follows:

• Within the Java development environment in Eclipse, click on the project, package, or class you want to use.
• Click on the "Project" menu item at the top of the Eclipse window, and select "Generate Javadoc...".
• A pop-up window will ask several questions regarding where to store the documentation.
  • A window pane with check boxes allows you to select which Project(s) will be used for generating documentation.
    • Click one or more projects if Javadocs are to be created for the entire project
    • Expand a triangle for a Project to find subdirectories. Source code for Java classes are located in the src subdirectory, so you might want to click on that triangle as well to identify what package(s) you want included.
  • A separate part of the pop-up box asks where the Javadocs are to be placed. Although the destination is up to you, one possibility might be a java directory located on your Desktop, as that might be easily accessible.
  • Click "Finish" when you have completed identifying your options.
• A sequence of progress reports may appear in the Console window. In some cases, if the Javadoc comments seem incomplete, you may receive some warning messages. (You may need to scroll up in the Console window to find the warnings with links to the relevant lines.)

Viewing Javadoc Documentation

The standard documentation for the Java class library is generated using the Javadoc system and may be found by accessing by the Java 9 API Specification site

This documentation shows the main layout of most Javadoc-generated documentation. A list of packages and/or classes appears on the left. When you click on a package, the classes for that package appear in the window below. When you click on a class, the documentation (e.g., for constructors, methods) appears in a window on the right.

To view your documentation, go to the directory you identified when you generated the Javadocs, and click on the name of a package.

created 10 February 2012 by Henry M. Walker revised 24 September 2014 revised 16 September 2018 revised 19 January 2020
For more information, please contact Henry M. Walker at walker@cs.grinnell.edu.