JavaDoc and Contracts
-
Upload
nevada-mcfarland -
Category
Documents
-
view
27 -
download
0
description
Transcript of 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