8/4/2019 javadoc-1

1/15

1

Documenting with

Javadoc

8/4/2019 javadoc-1

2/15

2

Outline

Motivation

Writing Javadoc comments

Running the javadoc tool

8/4/2019 javadoc-1

3/15

3

Motivation

Why document programs? To make it easy to understand, e.g., for

reuse and maintenance

What to document?

Interface: syntactic vs. semantic (or

behavioral) interfaces Internal working

8/4/2019 javadoc-1

4/15

4

Motivation (Cont.)

Why Javadoc? To combine source code with

documentation and other referencematerials

To make it easier to keep thedocumentation and code in sync

To generate API specifications (or interfacespecifications) from source code

8/4/2019 javadoc-1

5/15

5

Approach

Javadoc commentsAttach special comments, called

documentation comment(or doccomment) to classes, fields, and methods.

/** */

Javadoc tool Use a tool, calledjavadoc, to automatically

generate HTML pages from source code.

8/4/2019 javadoc-1

6/15

6

Javadoc Example/** An abstract class representing various kinds of shapes. */public abstract class Shape {

/** The x-coordinate of this shape. */private int x;

//

/** Returns the x-coordinate of this shape. */

public int getX() { }

/** Sets the x-coordinate of this shape to the argument* x.

*/

public void setX(int x) { }

// }

8/4/2019 javadoc-1

7/15

Example (Cont.)

8/4/2019 javadoc-1

8/15

8

Javadoc Tags

Javadoc Tags Special keyword recognized by javadoc tool. Will be specially formatted

Common Tags @author Author of the feature @version Current version number @since Since when

@param Meaning of parameter @return Meaning of return value @throws Meaning of exception @see Link to other features

8/4/2019 javadoc-1

9/15

9

Example/** An abstract class representing various kinds of

* shapes. This class represents common features* of all shapes such as *

* @author Yoonsik Cheon* @version 1.0 (01/22/04)* @since version 0.5*/

public abstract class Shape {//

}

8/4/2019 javadoc-1

10/15

10

Specifying Parameters andReturn Value

Syntax @param name description @return description @throws exception description

Example/** Returns the definition of a given word in this dictionary.** @param word a word whose definition is being looked

up.* @return the definition of the word; null if no definition

is* found.* @throws NullPointerException if the word is null.

*/public String lookup(String word) { /* */ }

8/4/2019 javadoc-1

11/15

Specifying Parameters (Cont.)

8/4/2019 javadoc-1

12/15

12

Linking to Other Features

Syntax @see featureName

where featureNameis class, field, or method.

Example@see Dictionary

@see #elems

@see #lookup(String)@see SpanishDictionary#lookup(String)

@see cs3331.Score#lookup(String)

8/4/2019 javadoc-1

13/15

13

Linking to Other Features(Cont.)

In-line link Used to refer features in a sentence. Syntax: {@linkfeatureName}

where featureNameis class, field, or method.

Example/** Returns the definition of a given word in this dictionary. This* method is overridden here from the class {@link Dictionary}* to implementSpanish-specific, efficient lookup algorithm.*

* @see Dictionary#lookup(String)* .*/

public String lookup(String word) { /* */ }

8/4/2019 javadoc-1

14/15

Linking (Cont.)

8/4/2019 javadoc-1

15/15

15

More Example/** An abstract class representing various kinds of shapes.

*

* @author Yoonsik Cheon* @version 1.0 (08/22/04)* @since version 0.5*/

public abstract class Shape {/** Returns the x-coordinate of this shape.

* @return the x-coordinate of this shape.*/

public int getX() { }

/** Sets the x-coordinate of this shape to the argument x.

* @param x the new x-coordinate.* @see #getX()*/

public void setX(int x) { }

//

}