Transcript Documenting with Javadoc Motivation  Why document programs?   To make it easy to understand, e.g., for reuse and maintenance What to document? Interface: syntactic vs.

Documenting with
Javadoc
1
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

2
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.
3
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
4
Self-documented Java code
5
Doc HTML page
6
Javadoc comments

Attach special comments, called documentation
comment (or doc comment) to classes, fields,
and methods.
/**
* ...
* . . . A (HTML) text . . .
* ..
*/
7
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) { … }
...
}
8
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.
Get the label.
(preferred)
(avoid)
9
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)
10
Javadoc Tags

Javadoc Tags



Special keyword recognized by javadoc tool.
Will be specially formatted
Common Tags







@param
@return
@throws
@author
@version
@see
@since
constructors, methods and interfaces only
methods only
@throws is a synonim added in Javadoc 1.2
classes and interfaces only, required
classes and interfaces only, required
(link to other features)
Since when …
11
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 {
// …
}
12
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) { /* … */ }
13
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)
14
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) { /* … */ }
15
Example: getImage
16
Example
17
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
18