1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments...
-
Upload
evangeline-hodges -
Category
Documents
-
view
222 -
download
1
description
Transcript of 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments...
![Page 1: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/1.jpg)
1
Documenting with Javadoc
CS 3331
Section 6.1.4 and Appendix B of [Jia03]How to Write Doc Comments for the JavadocTM Tool available from www.oracle.com
![Page 2: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/2.jpg)
2
Outline
Motivation Writing Javadoc comments Running the javadoc tool
![Page 3: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/3.jpg)
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
![Page 4: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/4.jpg)
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
![Page 5: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/5.jpg)
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.
![Page 6: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/6.jpg)
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) { … } // …}
![Page 7: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/7.jpg)
Example (Cont.)
![Page 8: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/8.jpg)
8
The First Sentence
Used to build table-of-contents for packages and classes
Be descriptive but concise Noun phrase for class and field Verb phrase for method
![Page 9: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/9.jpg)
9
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
![Page 10: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/10.jpg)
10
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 { // …}
![Page 11: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/11.jpg)
11
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) { /* … */ }
![Page 12: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/12.jpg)
Specifying Parameters (Cont.)
![Page 13: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/13.jpg)
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)@see cs3331.Score#lookup(String)
![Page 14: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/14.jpg)
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) { /* … */ }
![Page 15: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/15.jpg)
Linking (Cont.)
![Page 16: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/16.jpg)
16
More Example/** An abstract class representing various kinds of shapes. * * @author Yoonsik Cheon * @version 1.0 (08/22/04) * @since version 0.5 */public abstract class Shape { /** Returns the x-coordinate of this shape. * @return the x-coordinate of this shape. */ public int getX() { … }
/** Sets the x-coordinate of this shape to the argument <code>x</code>. * @param x the new x-coordinate. * @see #getX() */ public void setX(int x) { … } // …}
![Page 17: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/17.jpg)
17
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;}
![Page 18: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/18.jpg)
18
Running javadoc Tool
Similar to running javac, e.g., javadoc A.java javadoc A.java B.java javadoc *.java javadoc –d javadocs *.java
On EclipseSelect Export … > Java > Javadoc
![Page 19: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/19.jpg)
19
Running javadoc (Cont.)
Linking to existing API specificationsjavadoc –link file:c:/Software/jdk8/docs/api *.javajavadoc –link http://docs.oracle.com/javase/8/docs/api *.java
Including non-public featuresJavadoc –private *.java
![Page 20: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/20.jpg)
20
Running javadoc (Cont.)
Other options, refer to JDK tool docs, e.g., http://docs.oracle.com/javase/8/docs/technotes/tools/
windows/javadoc.html
![Page 21: 1 Documenting with Javadoc CS 3331 Section 6.1.4 and Appendix B of [Jia03] How to Write Doc Comments for the Javadoc TM Tool available from .](https://reader033.fdocuments.net/reader033/viewer/2022052706/5a4d1aca7f8b9ab05996f464/html5/thumbnails/21.jpg)
21
Other Resources Many on-line tips, guidelines, and other
documents, e.g., “How to Write Doc Comments for the JavadocTM Tool”
available at http://www.oracle.com/technetwork/articles/java/index-137868.html