Transcript 12-JavaDoc.v2.0.0

www.espirity.com
Javadoc
Dwight Deugo ([email protected])
Nesa Matic ([email protected])
Additional Contributors

None as of September, 2004
2
© 2003-2004, Espirity Inc.
Module Overview
1. Javadoc
2. Exporting Javadoc in Eclipse
3
© 2003-2004, Espirity Inc.
Module Road Map
1. Javadoc
Doclets
Comments
 Placement
 Sections
 Tags
 Running Javadoc
2. Exporting Javadoc in Eclipse


4
© 2003-2004, Espirity Inc.
Javadoc

Tool

Parses the declarations and documentation
comments in java source files and produces a
set of HTML (plus other format) pages
describing the classes
.html
.java
.java
Javadoc
.pdf
.rtf
.java
5
© 2003-2004, Espirity Inc.
Javadoc Doclets

Use Javadoc doclets to customize Javadoc output



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
You can write a doclet to generate any kind of text-file
output
Sun provides:



A "standard" doclet for generating HTML-format
An experimental MIF doclet for generating MIF, PDF, PS, RTF,
FrameMaker, and other formats
Doclets can also be used to perform special tasks not
related to producing API documentation
6
© 2003-2004, Espirity Inc.
Processing Source Files

Tool parses by default the following:







The public and protected classes
Nested classes (but not anonymous inner classes)
Interfaces
Constructors
Methods
Fields
Use the tool to generate the API documentation or
the implementation documentation for a set of
source files


Run the tool on packages and/or source files
Use Javadoc comments to customize documentation
7
© 2003-2004, Espirity Inc.
Running Javadoc

Tool normally processes files that end in .java



The tool can be run three ways without explicitly
specifying the source filenames:




Can run the tool by explicitly passing in individual source
filenames
Normally tool is run by passing package names
Passing in package names
Using –subpackages option
Using wildcards with source filenames (*.java)
The tool processes a .java file only if it fulfills all of the
following requirements:



The file, after removing the .java suffix, is a legal class name
The directory path relative to the root of the source tree is a
legal package name
The package statement contains the legal package name
8
© 2003-2004, Espirity Inc.
Javadoc Comments


Consists of the characters between the
characters /** that begin the comment and
the characters */ that end it
The text in a comment can continue onto
multiple lines
/**
* This is the typical format of a simple
* documentation comment
* that spans three lines. */
9
© 2003-2004, Espirity Inc.
Placement of Comments

Documentation comments are recognized only
when placed immediately before:







Class
Interface
Constructor
Method
Field declarations
Documentation comments placed in the body of a
method are ignored
Only one documentation comment per declaration
statement is permitted
10
© 2003-2004, Espirity Inc.
Class Comment Example
/**
* This is the class comment for the class MyClass
*/
public class MyClass{
…
}
11
© 2003-2004, Espirity Inc.
Comment Sections

The first sentence of a Javadoc comment is the
main description



The tag section starts with the first block tag




Provides a short description of the item
Begins after the starting delimiter /** and continues until
the tag section
Defined by the first @ character that begins a line
(ignoring leading asterisks, white space, and leading
separator /**)
It is possible to have a comment with only a tag section
and no main description
The argument to a tag can span multiple lines
There can be any number of tags
12
© 2003-2004, Espirity Inc.
Comment Sections Example
/**
* This is the class comment for the class MyClass
* and ends here
* @see eclipse.org.ecesis
*/
public class MyClass{
…
}
13
© 2003-2004, Espirity Inc.
Tags


A tag is a special keyword
There are two kinds of tags:

Block tags, which appear as @tag



Also known as "standalone" tags
Must appear at the beginning of a line, ignoring
leading asterisks, white space, and separator (/**)
In-line tags, which appear within curly braces, as
{@tag}

An in-line tag is allowed and interpreted anywhere
that text is allowed
14
© 2003-2004, Espirity Inc.
Tags Example
/**
* This is the class comment for the class MyClass
* and ends here
* @deprecated
*
replaced by {@link eclipse.org.ecesis.YourClass}
*/
public class MyClass{
…
}
15
© 2003-2004, Espirity Inc.
HTML Comments



Comments can contain standard HTML
Should use HTML entities and can use HTML
tags
Use whichever version of HTML your browser
supports
/**
* This is the <b>typical</b> format of a simple
* documentation comment
* that spans three lines.
*/
16
© 2003-2004, Espirity Inc.
Where Tags Can Be Used: Overview Tags

Overview Tags




Appear in the documentation comment for the overview
page
These tags must appear after the main description
Resides in the source file typically named overview.html
Include:







@see
@since
@author
@version
{@link}
{@linkplain}
{@docRoot}
17
© 2003-2004, Espirity Inc.
Where Tags Can Be Used: Package Tags

Package Tags



Appear in the documentation comment for a package
Resides in the source file named package.html
Include:









@see
@since
@deprecated
@serial
@author
@version
{@link}
{@linkplain}
{@docRoot}
18
© 2003-2004, Espirity Inc.
Where Tags Can Be Used: Class/Interface Tags

Class/Interface Tags


Appear in the documentation comment for a class or
interface
/**
* A class representing a window on the
Include:









@see
@since
@deprecated
@serial
@author
@version
{@link}
{@linkplain}
{@docRoot}
* screen.
* For example:
* <pre>
*
Car car = new Car();
*
car.go();
* </pre>
*
* @author Dwight Deugo
* @version 1.0
* @see
eclipse.org.ecesis.car
*/
class Car extends Vehicle {
...
}
19
© 2003-2004, Espirity Inc.
Where Tags Can Be Used: Field Tags

Field Tags


Appear in the documentation comment for a field
Include:
/**









@see
@since
@deprecated
@serial
@serialField
{@link}
{@linkplain}
{@docRoot}
{@value}
* The location of the car.
*
* @see #getLocation()
*/
int location = new Point(1,2);
20
© 2003-2004, Espirity Inc.
Where Tags Can Be Used: Method/Constructor Tags

Method/Constructor Tags


Appear in the documentation comment for a constructor or method
Include:












@see
/**
* Returns the car at the
@since
* specified location
@deprecated
* @param
index
the location of car.
@param
* @return
the desired car.
@return
* @exception IndexOutOfRangeException
@throws
* @see getLocation()
*/
@exception
public Car getCarAtLocation(Point location){
@serialData
...
{@link}
}
{@linkplain}
{@inheritDoc}
{@docRoot}
21
© 2003-2004, Espirity Inc.
Sample Output
22
© 2003-2004, Espirity Inc.
Running Javadoc Program

At the Command Prompt execute:
javadoc [options] <package> | <class>.java

Most commonly used options include:

-subpackages <package1>:<package2>



-exclude <packagename1>:<packagename2>
 Excludes specified packages and their subpackages.
-sourcepath <suurcepathlist>


Documentation generation from source files in the specified
packages and their subpackages.
Represents the search path for finding .java files. Multiple paths
can be specified by separating them with a semicolon.
-classpath <classpathlist>

Represents the search path for finding .class files. Multiple paths
can be specified by separating them with a semicolon.
23
© 2003-2004, Espirity Inc.
Full Documentation

The complete API is at

http://java.sun.com/j2se/1.4.2/docs/tooldocs/wi
ndows/javadoc.html
24
© 2003-2004, Espirity Inc.
Module Road Map
1.
Javadoc
2. Exporting Javadoc in Eclipse


Javadoc support in Eclipse
Using Eclipse to Export Javadoc
25
© 2003-2004, Espirity Inc.
Exporting Javadoc


Select the package and
then select Export …
from the Package
Explorer context menu
Select Javadoc as the
export destination
26
© 2003-2004, Espirity Inc.
Select Javadoc Options


Specify Javadoc
command to be used
Select your options




Types
Member visibility
Destination
Select Next
27
© 2003-2004, Espirity Inc.
Configure Javadoc Arguments…

Configure Javadoc
arguments for standard
doclet
28
© 2003-2004, Espirity Inc.
…Configure Javadoc Arguments


Configure extra
Javadoc arguments
Click Finish
29
© 2003-2004, Espirity Inc.
Module Summary

In this module we have discussed:


How to generate Java Document
Javadoc Tool



Comments and tags
Running the program
Javadoc support in Eclipse
30
© 2003-2004, Espirity Inc.
Labs Slide!
Lab: Javadoc
31
© 2003-2004, Espirity Inc.