CSC 207	Grinnell College	Spring, 2012

Algorithms and Object-Oriented Design

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.
- If you want to store the documentation within the Eclipse environment, you might specify:
```
   /home/username/workspace/Examples/doc
```
  This assumes you have specified a project name Examples within a workspace named workspace.
- If you would like to store documentation on a public site that could be viewed over the Web (e.g., by prospective employers), you might do the following:
  1. Within a terminal window, create a directory public_html in your home directory, if you have not created such a directory earlier. Once created, make that directory public:
```
mkdir public_html
chmod 755 public_html
```
  2. Within the public_html directory, make a subdirectory for public projects or for public documentation. Then make the subdirectory public. For example, if the subdirectory were called javadocs, you might use these steps in a terminal window, starting from your home directory.
```
cd public_html
mkdir javadocs
chmod 755 javadocs
```
  3. Once the subdirectory exists, specify it as the location for Eclipse to store the javadocs documentation. You may choose to use the browse option in Eclipse to find this subdirectory.
  4. Once Eclipse has generated the documentation (the next step below), go back to the terminal window and make the documentation public. Within the terminal window within the public_html directory, issue the following command:
```
chmod -R 755 javadocs/*
```
- Click "Finish" to complete the work.
A sequence of progress reports will 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, use your browser:

If you stored your javadoc documentation within Eclipse, the URL will be
```
   file:///home/username/Eclipseworkspace/index.html
```
(Note the 3 forward slash (/) characters after the colon in this address.)

For example, if you used the Eclipse workspace mentioned above when setting up Eclipse, and if your Eclipse is named Examples, then you could type the follwoing URL into your browser after generating your javadoc materials.
```
   file:///home/username/workspace/doc/index.html
```
If you stored your javadoc documentation in the javadocs subdirectory within public_html, and if you have made the directories and files public, then use the following URL:
```
http://www.cs.grinnell.edu/~username/javadocs/
```

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

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 United States License .