1. 1 Documenting with Javadoc

2. 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. 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. 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. 5 Self-documented Java code

6. 6 Doc HTML page

7. 7 Javadoc comments  Attach special comments, called documentation comment (or doc comment) to classe s, fields, and methods. /** *... *... A (HTML) text... *.. */

8. 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. 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. 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. 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. 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. 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. 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. 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. 16 Example: getImage

17. 17 Example

18. 18 Resources  Many on-line tips, guidelines, and other documents, e.g., “How to Write Doc Comments for the Javadoc TM Tool” available at http://java.sun.com/j2se/javadoc/writingdoccomments/index.html