1 / 16

Documenting Java Code

Documenting Java Code. Javadoc: The Tool and the Legend. Comments in Java. Regular Java comments: /* */ for programmers who must read or modify your code. “One Liners”: // for programmers who must read or modify your code. Javadoc comments: /** */ for those who must use your code.

evita
Download Presentation

Documenting Java Code

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 Java Code Javadoc: The Tool and the Legend

  2. Comments in Java • Regular Java comments: /* */ • for programmers who must read or modify your code. • “One Liners”: // • for programmers who must read or modify your code. • Javadoc comments: /** */ • for those who must use your code.

  3. General Form of a Doc Comment • The first line is indented to line up with the code below the comment, and starts with the begin-comment symbol (/**) followed by a return • Subsequent lines start with an asterisk *. They are indented an additional space so the asterisks line up. A space separates the asterisk from the descriptive text or tag that follows it. • Insert a blank comment line between the description and the list of tags, as shown. • Insert additional blank lines to create "blocks" of related tags • The last line begins with the end-comment symbol (*/) indented so the asterisks line up and followed by a return.Note that the end-comment symbol containsonly a single asterisk (*). /** * This is the description part of a doc comment * * @tag Comment for the tag */

  4. General Form of a Doc Comment (cont) • Break any doc-comment lines exceeding 80 characters in length, if possible. If you have more than one paragraph in the doc comment, separate the paragraphs with a <p> paragraph tag. • Comments can contain HTML tags (including links)

  5. First Sentence • should be a summary sentence, containing a concise but complete description of the API item • The Javadoc tool copies this first sentence to the appropriate member, class/interface or package summary • This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tag (as defined below). For example, this first sentence ends at "Prof.": • you can work around this by typing an HTML meta-character such as "&" or "<" immediately after the period, such as: /** * This is a simulation of Prof. Knuth's MIX computer. */ /** * This is a simulation of Prof.&nbsp; Knuth's MIX computer. */

  6. Tagged Paragraphs • Begin with @ followed by keyword • End at the next tag or end of the comment • Identify information that has routine structure

  7. @see • Used to specify a cross-reference • @see java.lang.String • @see String • @see java.io.InputStream; • @see String#equals • @see java.lang.Object#wait(int) • @see java.io.RandomAccessFile#RandomAccessFile(File, String) • @see Character#MAX_RADIX • @see <a href="spec.html">Java Spec</a>

  8. @author • May be used for class and interface declarations @author Mary Wollstonecraft • A documentation comment may contain more than one @author tag

  9. @version • May be used for class and interface declarations @version 493.0.1beta • A documentation comment may contain at most one version tag

  10. @param • May be used in comments for method and constructor declarations @param file the file to be searched • Parameters should be documented in the order in which they are declared

  11. @return • may be used in documentation comments for declarations of methods whose result type is not void @return the number of widgets to be used • Use to provide a short description of the return value

  12. @exception (@throws) • may be used in documentation comments for method and constructor declarations @exception IndexOutOfBoundsException the matrix is too large • The name of the class followed by a short description of when it is thrown

  13. @deprecated @deprecateddeprecated-text • Adds a comment indicating that this API should no longer be used (even though it may continue to work). Javadoc moves the deprecated-text ahead of the description, placing it in italics and preceding it with a bold warning: "Deprecated".

  14. JavaDoc Example /** * The root of the Class hierarchy. Every Class in the * system has Object as its ultimate parent. Every variable * and method defined here is available in every Object. * @see Class * @version 1.37, 26 Jun 1996 */ public class Object { /** * Compares two Objects for equality. * Returns a boolean that indicates whether this Object * is equivalent to the specified Object. This method is * used when an Object is stored in a hashtable. * @param obj the Object to compare with * @return true if these Objects are equal; * false otherwise. * @see java.util.Hashtable */ public boolean equals(Object obj) { return (this == obj); } /** * Creates a clone of the object. A new instance is * allocated and a bitwise clone of the current object * is placed in the new object. * @return a clone of this Object. * @exception OutOfMemoryError If there is not enough * memory. * @exception CloneNotSupportedException * Object explicitly does not want to be * cloned, or it does not support * the Cloneable interface. */

  15. Running Javadoc • Synopsis: javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ] • Example javadoc -sourcepath /java/my/src/share/classes -d /java/my/api me.pack1 me.pack2 • Generates Output in /java/my/api

  16. Links • http://java.sun.com/j2se/javadoc/writingdoccomments/index.html • http://java.sun.com/docs/books/jls/html/18.doc.html • http://java.sun.com/products/jdk/1.2/docs/tooldocs/win32/javadoc.html

More Related