Scribd
Upload
43 views

Documenting Java Code: Javadoc: The Tool and The Legend

Javadoc is a tool for generating API documentation from source code comments. It parses special Javadoc comments formatted with tags like @param, @return, and @see and uses this information to generate HTML documentation. The documentation includes descriptive text, lists of parameters, return values, exceptions, and cross-references to other classes. Javadoc comments are formatted with HTML tags and follow conventions like summarizing the purpose in the first sentence and grouping related tags together.

Uploaded by

Ankit Joshi
Copyright
© © All Rights Reserved
Available Formats
Download as PPT, PDF, TXT or read online on Scribd
43 views

Documenting Java Code: Javadoc: The Tool and The Legend

Javadoc is a tool for generating API documentation from source code comments. It parses special Javadoc comments formatted with tags like @param, @return, and @see and uses this information to generate HTML documentation. The documentation includes descriptive text, lists of parameters, return values, exceptions, and cross-references to other classes. Javadoc comments are formatted with HTML tags and follow conventions like summarizing the purpose in the first sentence and grouping related tags together.

Uploaded by

Ankit Joshi
Copyright
© © All Rights Reserved
Available Formats
Download as PPT, PDF, TXT or read online on Scribd
You are on page 1/ 16

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.

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 contains
only a single asterisk (*).
/**
* This is the description part of a doc comment
*
* @tag Comment for the tag
*/

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)

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.":
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/

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.&nbsp; Knuth's MIX computer.
*/

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

@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>

@author

May be used for class and


interface declarations
@author Mary Wollstonecraft

A documentation comment may


contain more than one @author
tag

@version

May be used for class and


interface declarations
@version 493.0.1beta

A documentation comment may


contain at most one version tag

@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

@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

@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

@deprecated
@deprecated deprecated-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".

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.
* @exceptionOutOfMemoryError
If there is not enough
*
memory.
* @exceptionCloneNotSupportedException
*
Object explicitly does not want to be
*
cloned, or it does not support
*
the Cloneable interface.
*/

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

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

You might also like