Session 6 of First Course in Java: Alex Aybes and Thomas Albert

Session 6 Lecture Notes for First Course in Java

JavaDoc

John Wenzler, Ph.D., of U.C. Berkeley wrote the following section.

Documenting Classes and Methods

This chapter teaches you how to produce simple API documentation for methods and classes with javadoc.

Writing Comments in the Source Code

Writing javadoc comments

Begin each javadoc comment with a backslash followed by two asterisks.
Begin each successive line with an asterisk.
Start the text on the second line, immediately after the single asterisk.
Close the comment with a single asterisk followed by a backslash.

Example:

/**
*This is the beginning of a javadoc comment.
*Start each new line with an asterisk.
*Close the comment with an asterisk and a backslash.
*/

Recognizing non-javadoc comments

You should be able to distinguish between documentation comments and "implementation comments," which are notes to programmers within a program. Javadoc does not read implementation comments.

There are two ways to make implementation comments. Multiple line comments begin with a backslash followed by a single asterisk. Single line comments begin with two backslashes.

Examples:

/*
*Javadoc will ignore this comment. It is an implementation comment,
* which describes the internal workings of a program.
*/

// This is another kind of implementation comment.

Putting Comments in the Right Place

Document public classes. By default, javadoc will not display comments for private classes.

Place documentation comments immediately above the method or class that you want to describe. Javadoc will ignore comments if there is a statement between the comment and the class or the method. (See the previous chapter for explanation of where methods and classes begin in code.)

Align the comment so that the left edge of the comment corresponds to the right edge of the class or the method.

Examples:

/**
*Javadoc will ignore this comment because the import statement
*comes between the comment and the beginning of the class.
*/
import java.awt.*;
public class myApplet extends Applet {

/**
*Because this comment documents a private method, it will not
* display unless you use a special command line option. Normally,
* you will not document private methods because your audience
* cannot access them.
*/
private void doSomething() {

import java.awt.*;
/**
* This comment is in the right place. Javadoc will read it.
*/
public class myApplet extends Applet { ...

Writing the First Sentence of a Comment

Make the first sentence of the comment a concise description of the method or class. Javadoc displays the first sentence in a summary screen next to a link. The reader must click the link to see the rest of the comment.

The first sentence ends after a period and a space. Be careful about using titles such as "Mr. Jones …" in the first sentence. For javadoc, the first sentence ends after "Mr." If you really need to include a period in the first sentence, use " " after the period.

Example:

/**
*Mr. Wenzler wrote this sentence, which will appear on
* the summary screen and in the index next to a link.
*Javadoc puts everything down here in the detailed description.
*The detailed description begins with the first sentence and
* continues with the rest of the comment.
*/
public void doSomething() { ...

Using HTML tags

To format the appearance of a comment, you can use HTML tags. Because javadoc handles most of the formatting, you do not need to know much HTML to write documentation comments. However, there are several important points to keep in mind.

Do not use header tags, such as <H1>, because they will disrupt the automatic formatting produced by javadoc
Surround blocks of code or the names of classes and methods with <CODE> …</CODE> or <PRE> …</PRE>
To emphasize a word or phrase, surround it with … 
To make a word or phrase bold face, surround it with … 
To start a new paragraph, use 
To break a line use 
To make unordered and ordered lists use <UL> … </UL> and <OL> … </OL>
To make the less than and greater than symbols "<" and ">" use "&lt" and "&gt

Example:

/**
*This comment demonstrates some HTML
*tags using a list and a line of code .
*
*Using HTML tags in javadoc comments allows you to:
*<ul>
*<li> make lists
*<li> include code samples
*<li> emphasize words
*</ul>
*
*This line of code tests whether the variable x is less than zero:
* <CODE> if (x &lt 0) { </CODE>
*/
public class MyClass1 { }

To see how javadoc formats these tags, look at the documentation for MyClass1.

Adding Links

Javadoc allows you to link your documentation to external files and Internet addresses. It also allows you to make links between different classes, constructors and methods in your own documentation. There are three ways to make a link:

With an HTML hyperlink
With an {@link} tag
With an @see tag

Using HTML hyperlinks

Because javadoc recognizes HTML tags, it allows you to make links as you would in any HTML file. For example, you can make a link to David J. Eck’s Java tutorial with the following tag:

<a href="http://math.hws.edu/javanotes/">Javanotes</a>

"Javanotes" is the label that the reader sees in the documentation. If the reader clicks on the link, the browser takes the reader to the web site for the book.

Using {@link} tags

{@link} tags are special javadoc tags that make links to javadoc documentation for other classes and methods. You can use an {@link} tag anywhere in a javadoc comment. To use {@link} use the syntax below:

{@link <package name>.<class name>#<method name><label>}

For example, to make a link to the setLabel() method of the Button class, write:

{@link java.awt.Button#setLabel() setLabel}

To make a link to the Button class in general, write:

{@link java.awt.Button Button}

Tip! By default, javadoc only produces links to methods and classes included in the current run of javadoc. If you are writing API documents for another company, javadoc will not create links to standard Sun classes, such as String and Button. To make links to the Java platform API, use the -link command line option described in the next section.

Tip! @link works with Java 2 and later versions of Java. If you are using Java 1.x, you will not be able to use @link.

Using the @see tag

The @see tag creates a separate "See Also" section at the bottom of a class or method description. The @see tag can refer to an Internet URL, a Java method or class, or an off-line resource such as a book.

Put an empty line with an asterisk between the text of the comment and the @see tag
Put the @see tag at the bottom of the comment on a new line
Start a new @see line for each reference
Put references to off-line resources between quotation marks
Use the {@link} format to make reference to Java classes and methods
Use HTML tags to make links to external Internet addresses or files

Example:

import java.awt.Component; // This statement is necessary to link to Button (see -link )
/**
*This comment demonstrates how to make links to different
*kinds of resources with javadoc.
*
*This is an in-line link to the Java method {@link Java.awt.Button}.
*
*This is a link to an external URL
*<a href=" http://java.sun.com/j2se/javadoc/index.html" > Javadoc
* Home Page </a>
*
*You also can use see also tags at the end of a comment.
*
* @see "Java 2: The Complete Reference by Herbert Schildt"
* @see java.lang.String#length()
* @see <a href=" http://java.sun.com/">Sun Microsystems</a>
*/
public class MyClass2 { }

To see how javadoc formats this comment, look at the generated documentation for MyClass2.

Using Other @tags

@param and @return

@param and @return tags describe the parameters and return types of methods and constructors. To use them:

Put @param and @return tags on a new line after the text of the comment
Put @param and @return tags before @see tags
Use @param tags only for methods and constructors
Use @return tags only for methods that have a return type.

Example:

/**
*This comment demonstrates the use of @param and @return
*tags.
*
* @param a an int value
* @param b an int value
* @return the smaller of a and b
* @see "Thinking in Java"
*/
public int getMin(int a, int b) { }

Click the getMin example documentation see how javadoc formats this comment.

@author and @since

@author indicates the author or authors of a class. @since describes which version of Java was used to write a class. To use these tags:

Put @author and @since at the end of a class comment, not at the end of a method or constructor comment.
Leave one blank line beginning with and asterisk after the text of the comment.
Put @author and @since tags before the @see tags.

Example:

/**
*This comment demonstrates where to put @author and @since
*tags in a class comment.
*
* @author John Wenzler
* @since version 1.3
* @see "Java: The Complete Reference"
*/

Creating stub files

You do not have to write complete Java programs to run javadoc. You can run javadoc on "stub files," which contain empty methods and classes. Software companies use this feature of javadoc to produce specifications before writing their programs. You also can use stub files for practice.

To create a stub file:

Write the signature for a class followed by a left curly bracket, "{"
Write the signature for methods and constructors in class followed by empty curly brackets, "{ }"
After writing the methods and constructors, close the class with a right curly bracket, "}"
Write javadoc comments above the signatures

Example:

/**
*Put a class comment here.
*/
public class MyClass {

/**
*Put a constructor comment here.
*/
public MyClass (int myParameter) { }
/**
*Put a method comment here.
*/
public String doSomething (double b) { }

} // The last curly bracket closes the class.

________________________
course homepage course calendar