JavaDoc and Contracts
Spring 2013
Documenting Contracts with
JavaDoc

Contract model for methods



JavaDoc



Preconditions
Postconditions
Industry standard for documenting APIs
Covers a lot more than contracts
How to go from one to the other?
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
Should be implementation *independent*



Also a useful document, but very different
Exceptions are highly undesirable
But are sometimes necessary
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
Preconditions?
Postconditions?
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 Style Hints from
Sun

Use <code></code> for keywords and names

Use inline links economically

Omit parenthesis for methods and constructors

Example add vs add(index, value)

Phrases instead of sentences ok

3rd person preferred to 2nd


gets the label vs. get the label
Begin method descriptions with a verb phrase

Gets the label… vs. This method gets the label…

Use “this” instead of “the” to refer to the object

Add description beyond API name
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
Directly supporting contracts


A variety of tools support design by
contract explicitly by extending Javadoc
Example: JML (Java Modeling Language)




@pre
@post
@inv
Various tools at JML Home Page
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