1 / 13

Documenting with Javadoc

Documenting with Javadoc. How to Write Doc Comments for the Javadoc TM Tool available from java.sun.com. Overview. Need for Javadoc Writing Javadoc comments Running the javadoc tool. Need for Javadoc. Why document programs? To make it easy to understand, e.g., for reuse and maintenance

emma-levine
Download Presentation

Documenting with Javadoc

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript


  1. Documenting with Javadoc How to Write Doc Comments for the JavadocTM Tool available from java.sun.com.

  2. Overview • Need for Javadoc • Writing Javadoc comments • Running the javadoc tool

  3. Need for Javadoc • 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. (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 * <code>x</code>. */ public void setX(int x) { … } // … }

  7. Javadoc Tags • Javadoc Tags • Special keyword recognized by javadoc tool. • Will be specially formatted • Common Tags • @author Author of the feature • @version Current version number • @since Since when • @param Meaning of parameter • @return Meaning of return value • @throws Meaning of exception • @see Link to other features

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

  9. Specifying Parameters and Return Value • Syntax • @param namedescription • @return description • @throws exceptiondescription • 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) { /* … */ }

  10. 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) @see cs3331.Score#lookup(String)

  11. 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; }

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

  13. Running javadoc (Cont.) • Linking to existing API specifications javadoc –link file:c:/Software/jdk1.6.0/docs/api *.java javadoc –link http://java.sun.com/j2se/1.6.0/docs/api *.java • Including non-public features Javadoc –private *.java

More Related