javadoc and contracts n.
Download
Skip this Video
Loading SlideShow in 5 Seconds..
JavaDoc and Contracts PowerPoint Presentation
Download Presentation
JavaDoc and Contracts

Loading in 2 Seconds...

play fullscreen
1 / 18

JavaDoc and Contracts - PowerPoint PPT Presentation


  • 183 Views
  • Uploaded on

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.

loader
I am the owner, or an agent authorized to act on behalf of the owner, of the copyrighted work described.
capcha
Download Presentation

PowerPoint Slideshow about 'JavaDoc and Contracts' - donatella


Download Now An Image/Link below is provided (as is) to download presentation

Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author.While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server.


- - - - - - - - - - - - - - - - - - - - - - - - - - E N D - - - - - - - - - - - - - - - - - - - - - - - - - -
Presentation Transcript
documenting contracts with javadoc
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
  • 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
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
Adding specification
  • Specifications are defined in comment lines.
  • /**

*This is the typical format of a *simpledocumentation comment that *spansthree lines.

*/

  • Inside the comment block, use <p> tags to separate paragraphs and javadoc pre-defined tags to define specific elements.
placement of comments
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
Structure of the specification

Main Description

Tag Section

Postconditions?

Preconditions?

comments are written in html
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 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
Overview Tags
  • @see
  • @since
  • @author
  • @version
  • {@link}
  • {@linkplain}
  • {@docRoot}
package tags
Package Tags
  • @see
  • @since
  • @author
  • @version
  • {@link}
  • {@linkplain}
  • {@docRoot}
class interface tags
Class/Interface Tags
  • @see
  • @since
  • @deprecated
  • @author
  • @version
  • {@link}
  • {@linkplain}
  • {@docRoot}
field tags
Field Tags
  • @see
  • @since
  • @deprecated
  • {@link}
  • {@linkplain}
  • {@docRoot}
  • {@value}
method constructor tags
Method/Constructor Tags
  • @see
  • @since
  • @deprecated
  • @param
  • @return
  • @throws / @exception
  • {@link}
  • {@linkplain}
  • {@inheritDoc}
  • {@docRoot}
javadoc style hints from sun
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
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
  • Choosethe 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
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
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