javadoc

1
javadoc
2
Purpose of javadoc

• javadoc is a program that reads your Java program
  and produces great-looking documentation in HTML
  format
• Without any help, javadoc will document the
  structure of your program
• javadoc will also read your specially-written
  javadoc comments and include them in its
  documentation

3
Advantages of javadoc

• Besides producing professional-looking
  documentation, javadoc also has these advantages
• Because the program documentation is right in the
  program itself, it's much easier to keep it up to
  date
• It's easy to recreate the documentation when the
  program is changed
• When working in a group, it's a really convenient
  way to see how to use the code written by others

4
Java documentation is in javadoc

• Sun's Java API (Application Programmer's
  Interface) is a wonderful resource
• Keep this open in a browser window when you are
  programming in Java
• Go to http//java.sun.com/j2se/1.3/docs/
• Click on Java 2 Platform API Specification
• Heres what it looks like

5
(No Transcript)
6
javadoc comments

• Ordinary comments / any text /
• javadoc comments / any text /
• / Single line comments are like this /
• / Multi-line comments are usually
  written like this the stars at the front of
  lines are ignored. /

7
What can be commented

• You can use javadoc comments for
• classes
• fields (variables)
• methods
• constructors
• interfaces
• javadoc ignores internal comments (in front of
  statements, blocks, etc.)

8
Placement of javadoc comments

• You can put a javadoc comment immediately before
  a class, field, method, constructor, or interface
• Nothing but whitespace can come between a javadoc
  comment and the thing being commented
• Badly placed javadoc comments are ignored

9
Examples

• / This is a comment for variable max /double
  maxdouble min / This comment is for avg
  /double avg
• / This comment is ignored. ///class
  Something . . .

10
HTML in javadoc

• If you know HTML, you can put some HTML commands
  in javadoc comments
• You can use bold, italic, paragraph, various
  kinds of lists, hypertext links, images, etc.
• You can not use document structuring commands,
  such as ltheadgt, lth2gt, or lthrgt

11
Special tags

• Special tags begin with _at_ and must be the first
  thing on the line
• Tags are used for describing parameters, return
  types, related methods, etc.
• You should always use the _at_author tag for class
  assignments
• Example
• _at_author John Q. Student

12
Running javadoc

• To run javadoc, usejavadoc -author -private
  -d dir .java
• The -author flag tells it not to ignore your
  _at_author comments
• The -private flag tells javadoc to document
  private, package, and protected items as well as
  public ones
• The -d flag names an existing directory for output

13
javadoc options

• javadoc has many options and is much more
  flexible than these slides suggest
• javadoc generates several HTML files, not just
  one
• Whenever you use javadoc, you should examine the
  results to make sure you got the results you
  expected

14
The End