JavaDoc

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
• simple documentation comment that
• spans three lines.
• /
• Inside the comment block, use ltpgt 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 class
  Whatever
• /
• 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 ltbgtdoclt/bgt comment.
• _at_see java.lang.Object
• /
• Note that tag names are case-sensitive. _at_See is
  an incorrect usage - _at_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 _at_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 _at_tag.
• /
• _at_deprecated As of JDK 1.1, replaced
• by _at_link setBounds(int,int,int,int)
• /

9
Overview Tags

• _at_see
• _at_since
• _at_author
• _at_version
• _at_link
• _at_linkplain
• _at_docRoot

10
Package Tags

• _at_see
• _at_since
• _at_author
• _at_version
• _at_link
• _at_linkplain
• _at_docRoot

11
Class/Interface Tags

• _at_see
• _at_since
• _at_deprecated
• _at_author
• _at_version
• _at_link
• _at_linkplain
• _at_docRoot

12
Field Tags

• _at_see
• _at_since
• _at_deprecated
• _at_link
• _at_linkplain
• _at_docRoot
• _at_value

13
Method/Constructor Tags

• _at_see
• _at_since
• _at_deprecated
• _at_param
• _at_return
• _at_throws / _at_exception
• _at_link
• _at_linkplain
• _at_inheritDoc
• _at_docRoot

14
Javadoc in Eclipse

• In Eclipse, to create Javadocs
• Go to File -gt Export -gt -gt 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

15
Example containsChar ()

• /
• Checks for character inclusion
• _at_param candidate String being searched for
  special characters
• _at_param characters String containing special
  characters for search
• _at_returns true iff candidate contains any
  character in "characters" ...
• _at_throws NullPointerException if either
  argument is null
• /
• public static boolean containsChar (String
  candidate, String characters)
• for (int i 0 i lt characters.length() i)
  
• if (candidate.indexOf(characters.charAt(i))
  gt 0)
• return true
• return false
• // Question Whats 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.ht
  ml
• How to Write Doc Comments for the Javadoc Tool
• http//java.sun.com/j2se/javadoc/writingdoccomment
  s/index.html
• http//java.sun.com/j2se/1.4.2/docs/tooldocs/windo
  ws/javadoc.html
• http//www.ibm.com/developerworks/java/library/j-j
  tp0821.html