Transcript Javadoc Summary

Javadoc Summary
Javadoc comments


Delemented by /** and */
Used to document
–
–
–

Classes
Methods
Fields
Must be placed immediately above the
feature it documents
Documentation


Each documentation comment contains
introductory text followed by tagged
documentation
Tags start with an @ character
–
–

@author
@param
First sentence should be a summary
statement
Documentation

HTML tags can be embedded
–
–
–
–
–
<em> emphasis
<code> for monospaced font
<img> for images
<ul> for bulleted lists
Etc.
Common javadoc Tags

@param parameter explanation
–
–

@return explanation
–

This is a parameter of a method.
Use a separate tag for each parameter
The return value of a method
@deprecated
–
A feature that remains for compatibility but that
should not be used for new code
Common javadoc Tags

@see packageName.ClassName
–

@author
–
–

A reference to a related documentation entry
The author of a class or interface
Use a separate tag for each author
@version
–
The version of a class or interface
Example – method documentation
/**
This method withdraws money from the bank account. It
increments the transaction count.
@param amount the amount to withdraw
@return the balance after the withdrawal
@throws IllegalArgumentException if balance is not sufficient
*/
public double withdraw (double amount) {
……….
}
To extract the comments

Run the javadoc program
–
javadoc sourceFile
Javadoc Command Line Options

-link URL
–
–
–

Link to another set of Javadoc files
Include a link to standard library documentation
(locally or at Sun web site
http://java.sun.com/javase/6/docs/api
-d directory
–
–
Store the output in directory
Keeps current directory uncluttered
Javadoc Command Line Options

-author
–
–

Include author information in the documentation
Author information is omitted by default
-version
–
–
Include version information in the documentation
Version information is omitted by default
Examples


javadoc –author BankAccount.java
Javadoc –author –version BankAccount.java
Files Produced by javadoc



Names of each HTML file created by javadoc
will be displayed
Produces an HTML file for the class named
BankAccount.html
If source file contains multiple classes or
interfaces, a separate HTML document is
created for each class.
Files Produced by javadoc

Creates an index.html file
–

Starting page
Creates index-all.html page
–
Contains alphabetical list of all classes,
interfaces, methods and fields
Example
javadoc –d Page –author –version Employee.java
index.html