Download JavaDoc and Contracts

Survey
yes no Was this document useful for you?
   Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Document related concepts
no text concepts found
Transcript
JavaDoc and Contracts
Fall 2008
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