Java Doc and Contracts Fall 2008 Documenting Contracts

Java. Doc and Contracts Fall 2008

Documenting Contracts with Java. Doc n Contract model for methods n n n Java. Doc n n n Preconditions Postconditions Industry standard for documenting APIs Covers a lot more than contracts How to go from one to the other?

Java. Doc n n Javadoc is a tool that generates java code documentation. Input: Java source files (. java) n n n Individual source files Root directory of the source files Output: HTML files documenting specification of java code n n One file for each class defined Package and overview files

Goal of an API specification n n Knowledge needed for “clean-room” implementation. Not a programming guide n n n Defines “contract” between callers and implementations Should be implementation *independent* n n n Also a useful document, but very different Exceptions are highly undesirable But are sometimes necessary Should contain assertions sufficient to test

Adding specification n 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 n 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. n 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 n * by {@link #set. Bounds(int, int)} */

Overview Tags n n n n @see @since @author @version {@link} {@linkplain} {@doc. Root}

Package Tags n n n n @see @since @author @version {@link} {@linkplain} {@doc. Root}

Class/Interface Tags n n n n @see @since @deprecated @author @version {@link} {@linkplain} {@doc. Root}

Field Tags n n n n @see @since @deprecated {@link} {@linkplain} {@doc. Root} {@value}

Method/Constructor Tags n @see n @since n @deprecated n @param n @return n @throws / @exception n {@link} n {@linkplain} n {@inherit. Doc} n {@doc. Root}

Java. Doc Style Hints from Sun n Use <code></code> for keywords and names n Use inline links economically n Omit parenthesis for methods and constructors n Example add vs add(index, value) n Phrases instead of sentences ok n 3 rd person preferred to 2 nd n n gets the label vs. get the label Begin method descriptions with a verb phrase n Gets the label… vs. This method gets the label… n Use “this” instead of “the” to refer to the object n Add description beyond API name

Javadoc in Eclipse In Eclipse, to create Javadocs: n Go to: File -> Export -> … -> Javadocs n Make sure the Javadoc command refers to the Javadoc command line tool n n For example: C: SunSDKjdkbinjavadoc. 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 n n A variety of tools support design by contract explicitly by extending Javadoc Example: JML (Java Modeling Language) n n @pre @post @inv Various tools at JML Home Page

Resources n Javadoc tutorial: n n Eclipse Javadoc configuration tutorial: n n 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 n n n http: //java. sun. com/j 2 se/javadoc/writingdoccomments/index. html http: //java. sun. com/j 2 se/1. 4. 2/docs/tooldocs/windows/javado c. html http: //www. ibm. com/developerworks/java/library/jjtp 0821. html