javadoc and contracts

JavaDoc and Contracts

Fall 2008

Documenting Contracts with JavaDoc

Contract model for methods Preconditions Postconditions

JavaDoc 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 Also a useful document, but very different

Defines “contract” between callers and implementations

Should be implementation *independent* 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:

http://bazaar.sis.pitt.edu/jdtutorial/index.html Eclipse Javadoc configuration tutorial:

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/javadoc.html

http://www.ibm.com/developerworks/java/library/j-jtp0821.html