1

Documenting with Javadoc

2

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

3

Motivation (Cont.)

If you find your programmer does not, or will not,

document their software, then it is best to get rid of

them now. If the software is undocumented and they

leave, the only option is to start again and rewrite it

all.

Picking up the pieces of poorly documented software

is a very expensive and a time-consuming exercise,

it’s cheaper to start from scratch.

4

Why Javadoc?

To combine source code with documentation and other reference materials

To make it easier to keep the documentation and code in sync

To generate API specifications (or interface specifications) from source code

5

Self-documented Java code

6

Doc HTML page

7

Javadoc comments

Attach special comments, called documentation comment (or doc comment) to classes, fields, and methods.

/**

* . . .

* . . . A (HTML) text . . .

* . .

*/

8

Javadoc Simple Example/** * An abstract class representing various kinds * of shapes. */public abstract class Shape { /** The x-coordinate of this shape. */ private double x; /** Returns the x-coordinate of this shape. */ public double getX() { … }

/** Set the x-coordinate of this shape to the * argument <code>x</code>. */ public void setX(double x) { … }

... }

9

Rules

• The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the API. • The Javadoc tool copies this first sentence to the appropriate member, class/interface or package summary. • Use <code> style for keywords and names.• Use 3rd person not 2nd person: Gets the label. (preferred) Get the label. (avoid)

10

Rules, cont.

•Methods description begins with a verb phrase Gets the label of this button

• Class/interface/field description can omit the subject and simply state the object. A button label (preferred) This field is a button label (avoid)

11

Javadoc Tags

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

Common Tags @param constructors, methods and interfaces only @return methods only @throws @throws is a synonim added in Javadoc 1.2 @author classes and interfaces only, required @version classes and interfaces only, required @see (link to other features) @since Since when …

12

Example

/** An abstract class representing various kinds of * shapes. This class represents common features * of all shapes such as … * * @author Bill Gates * @version 1.0 (01/10/2006) * @since version 0.5 */public abstract class Shape { // …}

13

Specifying Parameters and Return 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) { /* … */ }

14

Linking to Other Features

Syntax @see featureName

where featureName is class, field, or method.

Example@see Dictionary

@see #elems

@see #lookup(String)

@see SpanishDictionary#lookup(String)

15

Linking to Other Features, Cont.

In-line link Used to refer features in a sentence. Syntax: {@link featureName} where featureName is 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) { /* … */ }

16

Example: getImage

17

Example

18

Resources

Many on-line tips, guidelines, and other

documents, e.g.,“How to Write Doc Comments for the JavadocTM Tool” available at

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html