1 / 16

JavaDoc

JavaDoc. CS/SWE 332 Fall 2010. JavaDoc. Javadoc is a tool that generate s 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

srasheed
Download Presentation

JavaDoc

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 CS/SWE 332 Fall 2010

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

  3. 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 • Key idea I want to focus on in CS/SWE 332 • Should be implementation *independent* • Exceptions are highly undesirable • Should contain assertions sufficient to test

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

  5. 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 classWhatever */ import com.sun; // problem! public class Whatever {}

  6. Structure of the specification Main Description Tag Section

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

  8. 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)} */

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

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

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

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

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

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

  15. Example – containsChar () /** * Checks for character inclusion * * @param candidate String being searched for special characters * @param characters String containing special characters for search * * @returns true iff “candidate” contains any character in "characters" ... * @throws NullPointerException if either argument is null */ public static boolean containsChar (String candidate, String characters) { for (int i = 0; i < characters.length(); i++) { if (candidate.indexOf(characters.charAt(i)) >= 0) { return true; } } return false; } // Question: What’s the bug in this code?

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