JavaDoc and Contracts

1
JavaDoc and Contracts

• Fall 2008

2
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?

3
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

4
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

5
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 ltpgt tags to
  separate paragraphs and javadoc pre-defined tags
  to define specific elements.

6
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

7
Structure of the specification
Main Description
Tag Section
Postconditions?
Preconditions?
8
Comments are written in HTML

• /
• This is a ltbgtdoclt/bgt comment.
• _at_see java.lang.Object
• /
• Note that tag names are case-sensitive. _at_See is
  an incorrect usage - _at_see is correct.

9
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 _at_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 _at_tag.
• /
• _at_deprecated As of JDK 1.1, replaced
• by _at_link setBounds(int,int,int,int)
• /

10
Overview Tags

• _at_see
• _at_since
• _at_author
• _at_version
• _at_link
• _at_linkplain
• _at_docRoot

11
Package Tags

• _at_see
• _at_since
• _at_author
• _at_version
• _at_link
• _at_linkplain
• _at_docRoot

12
Class/Interface Tags

• _at_see
• _at_since
• _at_deprecated
• _at_author
• _at_version
• _at_link
• _at_linkplain
• _at_docRoot

13
Field Tags

• _at_see
• _at_since
• _at_deprecated
• _at_link
• _at_linkplain
• _at_docRoot
• _at_value

14
Method/Constructor Tags

• _at_see
• _at_since
• _at_deprecated
• _at_param
• _at_return
• _at_throws / _at_exception
• _at_link
• _at_linkplain
• _at_inheritDoc
• _at_docRoot

15
JavaDoc Style Hints from Sun

• Use ltcodegtlt/codegt 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

16
Javadoc in Eclipse

• In Eclipse, to create Javadocs
• Go to File -gt Export -gt -gt 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

17
Directly supporting contracts

• A variety of tools support design by contract
  explicitly by extending Javadoc
• Example JML (Java Modeling Language)
• _at_pre
• _at_post
• _at_inv
• Various tools at JML Home Page

18
Resources

• Javadoc tutorial
• http//bazaar.sis.pitt.edu/jdtutorial/index.html
• Eclipse Javadoc configuration tutorial
• http//open.ncsu.edu/se/tutorials/javadoc/index.ht
  ml
• How to Write Doc Comments for the Javadoc Tool
• http//java.sun.com/j2se/javadoc/writingdoccomment
  s/index.html
• http//java.sun.com/j2se/1.4.2/docs/tooldocs/windo
  ws/javadoc.html
• http//www.ibm.com/developerworks/java/library/j-j
  tp0821.html