Building Code Documentation using JavaDoc

1
Building Code Documentation using JavaDoc

• Samir Tartir
• Oct 2, 2008

2
JavaDoc

• Uses special comments in
• Packages
• Classes
• Methods
• Fields
• To generate HTML documentation from these comments

3
Example - Java

• /
• Returns an Image object that can then be
  painted on the screen.
• The url argument must specify an absolute
  _at_link URL. The name
• argument is a specifier that is relative to
  the url argument.
• _at_param url an absolute URL giving the base
  location of the image
• _at_param name the location of the image,
  relative to the url argument
• _at_return the image at the specified URL
• _at_see Image
• /
• public Image getImage(URL url, String name)
• try
• return getImage(new URL(url, name))
• catch (MalformedURLException e)
• return null

4
Example - HTML

• getImage
• public Image getImage(URL url,
• String name)
• Returns an Image object that can then be painted
  on the screen. The url argument must specify an
  absolute URL. The name argument is a specifier
  that is relative to the url argument.
• Parameters
• url - an absolute URL giving the base location of
  the image
• name - the location of the image, relative to the
  url argument
• Returns
• the image at the specified URL
• See Also
• Image

5
Class and interface comments

• Comments should be placed immediately before
• class or interface
• Starts with / and finishes with /
• First sentence is a summary
• tag section
• _at_author - name and email
• _at_version - version and date
• _at_exception or _at_throws - exceptions of the class
  (optional)
• _at_see - references (optional)

6
Example

• /
• Summary of ltigtclass/interface descriptionlt/igt
• ltpgt
• Main description of class/interface
• as HTML text
• _at_author John Smith
• _at_version 1.0, Jan/1/2008
• _at_see MyInterface
• /
• public class MyClass implements MyInterface
• ...

7
Method and constructor comments

• Same as in class as interface
• Tags
• no _at_author
• no _at_version
• _at_param - name of argument and description
• _at_return - description (only for methods which
• return value is not void)
• _at_throws- exception name and description
• _at_see - reference (optional)

8
Field (attribute) comments

• Contains
• main description
• tag _at_see
• Example
• /
• The X-coordinate of the component.
• _at_see getLocation()
• /
• int x 1263732

9
JavaDocs Home on the Web

• http//java.sun.com/j2se/javadoc/