1 / 18

Effective JavaDoc Documentation for Contracts and API Specification

This resource covers the importance of JavaDoc in documenting contracts between callers and implementations in Java. It emphasizes the need for clear preconditions and postconditions, specifying the structure of JavaDoc comments, and adhering to industry standards for API documentation. The guide also highlights tools and methods for generating HTML documentation from Java source files, along with tips for best practices in writing JavaDoc comments. Learn how to effectively communicate APIs and ensure your Java code is well-documented and understood.

winona
Télécharger la présentation

Effective JavaDoc Documentation for Contracts and API Specification

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. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  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 *simpledocumentation comment that *spansthree lines. */ • Inside the comment block, use <p> 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 <b>doc</b> comment. * @see java.lang.Object */ Note that tag names are case-sensitive. @See is an incorrect usage - @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: @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)} */

  10. Overview Tags • @see • @since • @author • @version • {@link} • {@linkplain} • {@docRoot}

  11. Package Tags • @see • @since • @author • @version • {@link} • {@linkplain} • {@docRoot}

  12. Class/Interface Tags • @see • @since • @deprecated • @author • @version • {@link} • {@linkplain} • {@docRoot}

  13. Field Tags • @see • @since • @deprecated • {@link} • {@linkplain} • {@docRoot} • {@value}

  14. Method/Constructor Tags • @see • @since • @deprecated • @param • @return • @throws / @exception • {@link} • {@linkplain} • {@inheritDoc} • {@docRoot}

  15. 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

  16. 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

  17. 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

  18. 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

More Related