Transcript JavaDoc

JavaDoc
CS/SWE 332
Fall 2010
JavaDoc


Javadoc is a tool that generates java code
documentation.
Input: Java source files (.java)



Individual source files
Root directory of the source files
Output: HTML files documenting
specification of java code


One file for each class defined
Package and overview files
Goal of an API specification


Knowledge needed for “clean-room”
implementation.
Not a programming guide


Defines “contract” between callers and
implementations


Key idea I want to focus on in CS/SWE 332
Should be implementation *independent*


Also a useful document, but very different
Exceptions are highly undesirable
Should contain assertions sufficient to test
Adding specification

Specifications are defined in comment
lines.
/**
* This is the typical format of a
* simple documentation comment that
* spans three lines.
*/

Inside the comment block, use <p> tags to separate
paragraphs and javadoc pre-defined tags to define
specific elements.
Placement of comments

All comments are placed immediately before
class, interface, constructor, method, or
field declarations. Other stuff between them
is not permitted.
/**
* This is the class comment for the class Whatever
*/
import com.sun; // problem!
public class Whatever {}
Structure of the specification
Main Description
Tag Section
Comments are written in
HTML
/**
* This is a <b>doc</b> comment.
* @see java.lang.Object
*/
Note that tag names are case-sensitive.
@See is an incorrect usage - @see is
correct.
Block tags and in-line tags
Block tags - Can be placed only in the tag section
that follows the main description. Block tags are of
the form: @tag.
 Inline tags - Can be placed anywhere in the main
description or in the comments for block tags.
Inline tags are denoted by curly braces: {@tag}.
/**
* @deprecated As of JDK 1.1, replaced

* by {@link #setBounds(int,int,int,int)}
*/
Overview Tags







@see
@since
@author
@version
{@link}
{@linkplain}
{@docRoot}
Package Tags







@see
@since
@author
@version
{@link}
{@linkplain}
{@docRoot}
Class/Interface Tags








@see
@since
@deprecated
@author
@version
{@link}
{@linkplain}
{@docRoot}
Field Tags







@see
@since
@deprecated
{@link}
{@linkplain}
{@docRoot}
{@value}
Method/Constructor Tags

@see

@since

@deprecated

@param

@return

@throws / @exception

{@link}

{@linkplain}

{@inheritDoc}

{@docRoot}
Javadoc in Eclipse
In Eclipse, to create Javadocs:

Go to: File -> Export -> … -> Javadocs
 Make sure the Javadoc command refers to the Javadoc
command line tool




For example: C:\Sun\SDK\jdk\bin\javadoc.exe
Select the types that you want to create Javadoc for
Choose the Use Standard Doclet radio button, and
Browse for a destination folder
Click Next for more options, enter custom tags in the
options text field
Example – containsChar ()
/**
*
*
*
*
*
*
*
*/
Checks for character inclusion
@param candidate String being searched for special characters
@param characters String containing special characters for search
@returns true iff “candidate” contains any character in "characters" ...
@throws NullPointerException if either argument is null
public static boolean containsChar (String candidate, String characters) {
for (int i = 0; i < characters.length(); i++) {
if (candidate.indexOf(characters.charAt(i)) >= 0) {
return true;
}
}
return false;
}
// Question: What’s the bug in this code?
Resources

Javadoc tutorial:


Eclipse Javadoc configuration tutorial:


http://bazaar.sis.pitt.edu/jdtutorial/index.html
http://open.ncsu.edu/se/tutorials/javadoc/index.html
How to Write Doc Comments for the Javadoc Tool



http://java.sun.com/j2se/javadoc/writingdoccomments/index.
html
http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javado
c.html
http://www.ibm.com/developerworks/java/library/jjtp0821.html