1 Documenting with Javadoc CS 3331 Fall 2009 How to Write Doc Comments for the Javadoc TM Tool available from java.sun.com.

2 Outline  Motivation  Writing Javadoc comments  Running the javadoc tool

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

4 Motivation (Cont.)  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 Approach  Javadoc comments Attach special comments, called documentation comment (or doc comment) to classes, fields, and methods. /** … */  Javadoc tool Use a tool, called javadoc, to automatically generate HTML pages from source code.

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) { … } // … }

Example (Cont.)

8 Javadoc Tags  Javadoc Tags Special keyword recognized by javadoc tool. Will be specially formatted  Common of the version of of return of to other features

9 Example /** An abstract class representing various kinds of * shapes. This class represents common features * of all shapes such as … * Yoonsik Cheon 1.0 (01/22/04) version 0.5 */ public abstract class Shape { // … }

10 Specifying Parameters and Return Value  name exception description  Example /** Returns the definition of a given word in this dictionary. * word a word whose definition is being looked up. the definition of the word; null if no definition is * found. NullPointerException if the word is null. */ public String lookup(String word) { /* … */ }

Specifying Parameters (Cont.)

12 Linking to Other Features  featureName where featureName is class, field, or method.  cs3331.Score#lookup(String)

13 Linking to Other Features (Cont.)  In-line link Used to refer features in a sentence. Syntax: 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 Dictionary} * to implementSpanish-specific, efficient lookup algorithm. * Dictionary#lookup(String) * …. */ public String lookup(String word) { /* … */ }

Linking (Cont.)

15 More Example /** An abstract class representing various kinds of shapes. * Yoonsik Cheon 1.0 (08/22/04) version 0.5 */ public abstract class Shape { /** Returns the x-coordinate of this shape. the x-coordinate of this shape. */ public int getX() { … } /** Sets the x-coordinate of this shape to the argument x. x the new x-coordinate. #getX() */ public void setX(int x) { … } // … }

16 Exercise  Write Javadoc comments for the following class. public class ArrayStack { public ArrayStack(int size) { … } public Object push(Object elem) { … } public Object pop() throws StackEmptyException { … } private Object[] elems; private int idx; }

17 Running javadoc Tool  Similar to running javac, e.g., javadoc A.java javadoc A.java B.java javadoc *.java javadoc –d javadocs *.java

18 Running javadoc (Cont.)  Linking to existing API specifications javadoc –link file:c:/Software/jdk1.6.0/docs/api *.java javadoc –link *.java  Including non-public features Javadoc –private *.java

19 Running javadoc (Cont.)  Other options, refer to JDK tool docs, e.g.,

20 Other Resources  Many on-line tips, guidelines, and other documents, e.g., “How to Write Doc Comments for the Javadoc TM Tool” available at dex.html dex.html