Javadoc Summary

1
Javadoc Summary
2
Javadoc comments

• Delemented by / and /
• Used to document
• Classes
• Methods
• Fields
• Must be placed immediately above the feature it
  documents

3
Documentation

• Each documentation comment contains introductory
  text followed by tagged documentation
• Tags start with an _at_ character
• _at_author
• _at_param
• First sentence should be a summary statement

4
Documentation

• HTML tags can be embedded
• ltemgt emphasis
• ltcodegt for monospaced font
• ltimggt for images
• ltulgt for bulleted lists
• Etc.

5
Common javadoc Tags

• _at_param parameter explanation
• This is a parameter of a method.
• Use a separate tag for each parameter
• _at_return explanation
• The return value of a method
• _at_deprecated
• A feature that remains for compatibility but that
  should not be used for new code

6
Common javadoc Tags

• _at_see packageName.ClassName
• A reference to a related documentation entry
• _at_author
• The author of a class or interface
• Use a separate tag for each author
• _at_version
• The version of a class or interface

7
Example method documentation

• /
• Withdraws money from the bank account.
  Increments the transaction count.
• _at_param amount the amount to withdraw
• _at_return the balance after the withdrawal
• _at_throws IllegalArgumentException if balance is
  not sufficient
• /
• public double withdraw (double amount)
• .

8
To extract the comments

• Run the javadoc program
• javadoc sourceFile

9
Javadoc Command Line Options

• -link URL
• Link to another set of Javadoc files
• Include a link to standard library documentation
  (locally or at Sun web site
• http//java.sun.com/j2se/1.5.0/docs/api
• -d directory
• Store the output in directory
• Keeps current directory uncluttered

10
Javadoc Command Line Options

• -author
• Include author information in the documentation
• Author information is omitted by default
• -version
• Include version information in the documentation
• Version information is omitted by default

11
Examples

• javadoc author BankAccount.java
• Javadoc author version BankAccount.java

12
Files Produced by javadoc

• Names of each HTML file created by javadoc will
  be displayed
• Produces an HTML file for the class named
  BankAccount.html
• If source file contains multiple classes or
  interfaces, a separate HTML document is created
  for each class.

13
Files Produced by javadoc

• Creates an index.html file
• Starting page
• Creates index-all.html page
• Contains alphabetical list of all classes,
  interfaces, methods and fields

14
Example

• javadoc d Page author version Employee.java
• index.html