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 classe s, 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 x. */ 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 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 constructors, methods and interfaces is a synonim added in Javadoc classes and interfaces only, classes and interfaces only, (link to other Since when …

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

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

14 Linking to Other Features  featureName where featureName is class, field, or method.  SpanishDictionary#lookup(String)

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

16 Example: getImage

17 Example

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