Transcript Documentation Comments

Literate Programming

Overview
Introduction to javadoc.

Documentation comments.

Documenting java source code.

Generating HTML documentation using javadoc.

Customizing javadoc output: doclets.

Preview: Further OO concepts.
Lecture 3
1
Literate Programming in Java
 Literate programming is the combination of documentation and source
together in a fashion suited for reading by human beings
 It is an easy way of creating reports and documentation at the same
time as the program itself, and usually produces nice-looking code as
well.
 Java supports three kinds of comments:
 /* text */ A traditional comment:
 // text A single-line comment:
 /** documentation */ A documentation comment:
 The text enclosed by the ASCII characters /** and */ can be processed
by a separate tool to prepare automatically generated documentation
of the following class, interface, constructor, or member (method or
field) declaration.
 Before discussing how documentations are produced let us first
describe the java tool used for the task.
Lecture 3
2
Program Comments and javadoc
 javadoc is the java tool used to create nice documentation from java programs.
 Before javadoc can generate HTML files, you must insert documentation
comments in your source program.
 Like other commands, documentation comments are not translated into bytecode.
 Because javadoc generates HTML, documentation comments can contain HTML
tags.
 Like HTML tags, javadoc tags (which begin with the @ symbol) can be inserted
into documentation comments.
 Documentation comments are placed on the line before a class definition, an
interface definition, a constructor, a method, and a field.
Lecture 3
3
Some javadoc Tags
Tag
Meaning
@author
Identifies the author of the class
@deprecated
Specifies that a class member is deprecated
@exception
Identifies an exception thrown by a method
@param
Documents a method's parameter
@return
Documents a method's return value
@see
Specifies a link to another topic
@since
States the release when a specific change was introduced
@throws
Same as @throws
@version
Specifies the version of a class
Lecture 3
4
@see Tag: Some Details
The @see Tag: In the previous slide, we have seen various uses of the
@see tag. This tag may be used in any documentation comment to indicate
a cross-reference to a class, interface, method, constructor, field, or URL
such as:
@see java.lang.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>
The character # separates the name of a class from the name of one of its
fields, methods, or constructors. One of several overloaded methods or
constructors may be selected by including a parenthesized list of argument
types after the method or constructor name. A documentation comment may
contain more than one @see tag.
Lecture 3
5
@author Tag: Some Details
The @author Tag: The following are examples of @author taglines, which
may be used in documentation comments for class and interface declarations:
@author Mary Wollstonecraft
@author Hildegard von Bingen
@author Dorothy Parker
The information in an @author paragraph has no special internal structure.
A documentation comment may contain more than one @author tag.
Alternatively, a single @author paragraph may mention several authors:
@author Jack Kent, Peggy Parish, Crockett Johnson,
James Marshall, Marjorie Weinman Sharmat,
Robert McCloskey, and Madeleine L'Engle
However, Gosling et al. recommend specifying one author per
@author paragraph, which allows the documentation processing tool to provide
the correct punctuation in all circumstances.
Lecture 3
6
@version Tag: Some Details
The @version Tag: The following is an example of a @version paragraph,
which may be used in documentation comments for class and interface
declarations: @version 493.0.1 beta
The information in a @version paragraph has no special internal structure.
A documentation comment may contain at most one @version tag.
The @param Tag: The following are examples of @param paragraphs, which
may be used in documentation comments for method and constructor
declarations:
@param file - The file to be searched.
@param pattern - The pattern to be matched during the search.
@param count - The number of lines to print for each match.
The information in a @param paragraph should consist of the name of the
parameter followed by a short description. A documentation comment may
contain more than one @param tag.
Lecture 3
7
@param and @return Tags: Some Details
The usual convention is that if any @param paragraphs are present in a
documentation comment, then there should be one @param paragraph for
each parameter of the method or constructor, and the @param paragraphs
should appear in the order in which the parameters are declared.
The @return Tag: The following is an example of a @return paragraph,
which may be used in documentation comments for declarations of methods
whose result type is not void:
@return the number of widgets that pass the quality test
The information in a @return paragraph has no special internal structure.
The usual convention is that it consists of a short description of the returned
value. A documentation comment may contain at most one @return tag.
Lecture 3
8
@exception Tag: Some Details
The @exception Tag: The following is an example of an @exception
paragraph, which may be used in documentation comments for method
and constructor declarations:
@exception IndexOutOfBoundsException the matrix is too large
@exception java.io.FileNotFoundException the file does not exist
The information in an @exception paragraph should consist of the name
of an exception class (which may be a simple name or a qualified name)
followed by a short description of the circumstances that cause the
exception to be thrown. A documentation comment may contain more
than one @exception tag.
Lecture 3
9
Using Javadoc Program: More Examples
/**
* @(#)Object.java 1.37 96/06/26
*/
package java.lang;
/**
* The root of the Class hierarchy.
* @see
Class
* @version
1.37, 26 Jun 1996
*/
public class Object {
public final native Class getClass();
/**
* Note: hashcodes can be negative as well as positive.
* @see java.util.Hashtable
*/
Lecture 3
10
Using Javadoc Program: More Examples (Cont’d)
public native int hashCode();
/**
* Compares two Objects for equality.
* @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.
* @return
a clone of this Object.
* @exception OutOfMemoryError If there is not enough memory.
* @exception CloneNotSupportedException Object
*/
Lecture 3
11
Using Javadoc Program: More Examples (Cont’d)
protected native Object clone() throws
CloneNotSupportedException;
/**
* Notifies a single waiting thread on a change in
* condition of another thread. The thread effecting
* the change notifies the waiting thread using notify().
* Threads that want to wait for a condition to change
* before proceeding can call wait(). <p>
* <em>The method notify() can be called only by the
* thread that is the owner of the current object's
* monitor lock.</em>
* @see
Object#wait
* @see
Object#notifyAll
*/
Lecture 3
12
Documentation Comments: Example 2
import java.io.*;
/**
* This class demonstrates documentation comments.
* @author ICS201 Instructor
* @version 1.2
*/
public class SquareNum {
/**
* This method returns the square of num.
* This is a multiline description. You can use
* as many lines as you like.
* @param num The value to be squared.
* @return num squared.
*/
public double square (double num) {
return num*num;
}
Lecture 3
13
Documentation Comments: Example 2 (cont.)
/** This method inputs a number from the user.
* @return The value input as a double.
* @see IOException
*/
public double getNumber() throws IOException {
// create a BufferedReader using System.in
InputStreamReader isr = new
InputStreamReader(System.in);
BufferedReader inData = new BufferedReader(isr);
String str;
double d;
str = inData.readLine();
d = Double.parseDouble(str);
return d;
}
Lecture 3
14
Documentation Comments: Example 2 (cont.)
/**
* This method demonstrate square
* @param args Unused.
* @return Nothing.
* @exception IOException on input error.
* @see IOException
*/
public static void main(String [] args) throws
IOException {
SquareNum ob = new SquareNum();
double val;
System.out.println("Enter value to be squared:" );
val = ob.getNumber();
val = ob.square(val);
System.out.println("Squared value is :"+ val);
}
}
Lecture 3
15
Generating HTML with javadoc: Some command-line options
usage: javadoc [options] [packagenames] [sourcefiles] [classnames] [@files]
-overview <file> Read overview documentation from HTML file
-public
Show only public classes and members
-protected Show protected/public classes and members (default)
-package
Show package/protected/public classes and members
-private
Show all classes and members
-help
Display command line options
-doclet <class> Generate output via alternate doclet
-sourcepath <pathlist> Specify where to find source files
Provided by Standard doclet:
-d <directory>
Destination directory for output files
-version
Include @version paragraphs
-author
Include @author paragraphs
-link <url>
Create links to javadoc output at <url>
Lecture 3
16
Adding Documentations: Points to Note

javadoc will run on .java source files that are pure stub files with no method
bodies.

Placing an import statement between the class documentation and the class
declaration is a logic error. This causes the class comment to ignored by javadoc.

Each tag should start on a new line. The tag comments can extend into multiple
lines if necessary, but there should be no blank lines in between tags.

Defining several fields in one comma-separated statement with a single comment
above that statement, will result in javadoc using that comment for all the fields.

To produce proper javadoc documentation, you must declare every instance
variable on a separate line.
Lecture 3
17
Customizing javadoc’s Output: Doclets





A doclet is a program written with the doclet API that specifies the content and
format of the output to be generated by the javadoc tool.
You can write a doclet to generate any kind of text-file output, such as HTML,
SGML, XML, RTF, and MIF.
If you do not supply a custom doclet, javadoc uses the default doclet provided by
java to generate HTML.
Alternatively, you can subclass appropriate classes in the standard doclet and then
add or override methods as necessary to produce the output you want.
A doclet is a program of the form (compiled using javac and passed to javadoc
using the –doclet option):
import com.sun.javadoc.*;
public class MyDoclet{
public static boolean
start(RootDoc rd){
…
}
}
Lecture 3
18
Writing Doclets: An Example
import com.sun.javadoc.*;
public class ListClass {
public static boolean start(RootDoc root) {
[]ClassDoc [] classes =
root.classes();
for (int i = 0;
i<classes.length; ++i)
System.out.println(classes[i]);
return true;
} }
 We must imports the com.sun.javadoc package in order to use the doclet
APIs.
 The start() method takes a RootDoc parameter that carries information about
any options specified on the command line when javadoc is run, and also about
the classes and packages upon which javadoc is operating.
 RootDoc defines a classes() method that returns a ClassDoc array whose
elements represent the classes that javadoc parses.
Lecture 3
19
Writing Doclets: An Example
 The doclet API classfiles are in the file lib/tools.jar in the Java 2 SDK, and
you therefore need to include tools.jar on the compiler's classpath, as in this
example:
C:\>javac -classpath C:\jdk1.3\lib\tools.jar ListClass.java
 We now run javadoc on MyClass.java using the ListClass doclet as:
C:\>javadoc -doclet ListClass -classpath C:\jdk1.3\lib\tools.jar MyClass.java
 Note that this command also requires tools.jar to be on the class path.
 For further details on this check the javadoc documentation in your JavaCD.
 Exercise: Explore the javadoc documentation and try to create your own custom
tags.
Lecture 3
20