JavaDoc and Contracts Spring 2013

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 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 doc comment. java.lang.Object */ Note that tag names are is an incorrect usage 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 Inline tags - Can be placed anywhere in the main description or in the comments for block tags. Inline tags are denoted by curly braces: /** As of JDK 1.1, replaced * by #setBounds(int,int,int,int)} */

@version

@deprecated

JavaDoc Style Hints from Sun Use 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 3 rd person preferred to 2 nd 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 @inv Various tools at JML Home PageJML Home Page

Resources Javadoc tutorial: Eclipse Javadoc configuration tutorial: How to Write Doc Comments for the Javadoc Tool html html c.html c.html jtp0821.html jtp0821.html