Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
JavaDoc CS/SWE 332 Fall 2010 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 Knowledge needed for “clean-room” implementation. Not a programming guide Defines “contract” between callers and implementations Key idea I want to focus on in CS/SWE 332 Should be implementation *independent* Also a useful document, but very different Exceptions are highly undesirable Should contain assertions sufficient to test 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. 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 Main Description Tag Section 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 - 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 @see @since @author @version {@link} {@linkplain} {@docRoot} Package Tags @see @since @author @version {@link} {@linkplain} {@docRoot} Class/Interface Tags @see @since @deprecated @author @version {@link} {@linkplain} {@docRoot} Field Tags @see @since @deprecated {@link} {@linkplain} {@docRoot} {@value} Method/Constructor Tags @see @since @deprecated @param @return @throws / @exception {@link} {@linkplain} {@inheritDoc} {@docRoot} 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 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? Resources Javadoc tutorial: Eclipse Javadoc configuration tutorial: http://bazaar.sis.pitt.edu/jdtutorial/index.html 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/javado c.html http://www.ibm.com/developerworks/java/library/jjtp0821.html