JavaDoc and Contracts
-
Upload
nevada-mcfarland -
Category
Documents
-
view
27 -
download
0
description
Transcript of JavaDoc and Contracts
![Page 1: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/1.jpg)
JavaDoc and Contracts
Fall 2008
![Page 2: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/2.jpg)
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?
![Page 3: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/3.jpg)
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
![Page 4: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/4.jpg)
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
![Page 5: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/5.jpg)
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.
![Page 6: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/6.jpg)
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 {}
![Page 7: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/7.jpg)
Structure of the specification
Main Description
Tag Section
Preconditions? Postconditions?
![Page 8: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/8.jpg)
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.
![Page 9: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/9.jpg)
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)}
*/
![Page 10: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/10.jpg)
Overview Tags @see @since @author @version {@link} {@linkplain} {@docRoot}
![Page 11: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/11.jpg)
Package Tags
@see @since @author @version {@link} {@linkplain} {@docRoot}
![Page 12: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/12.jpg)
Class/Interface Tags @see @since @deprecated @author @version {@link} {@linkplain} {@docRoot}
![Page 13: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/13.jpg)
Field Tags @see @since @deprecated {@link} {@linkplain} {@docRoot} {@value}
![Page 14: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/14.jpg)
Method/Constructor Tags @see @since @deprecated @param @return @throws / @exception {@link} {@linkplain} {@inheritDoc} {@docRoot}
![Page 15: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/15.jpg)
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
![Page 16: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/16.jpg)
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
![Page 17: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/17.jpg)
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
![Page 18: JavaDoc and Contracts](https://reader036.fdocuments.net/reader036/viewer/2022083004/56812e8a550346895d942d08/html5/thumbnails/18.jpg)
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