Transcript javadoc
javadoc
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 speciallywritten “javadoc comments” and include
them in its documentation
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
• Here’s what it looks like:
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.
*/
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.)
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
Examples
• /** This is a comment for variable max */
double max;
double min; /** This comment is for avg */
double avg;
• /** This comment is ignored. */
//
class Something { . . . }
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 <head>, <h2>, or <hr>
Special tags
• Special tags begin with @ 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 @author tag for
class assignments
• Example:
– @author John Q. Student
Running javadoc
• To run javadoc, use:
javadoc -author -private *.java
• The -author flag tells it not to ignore your
@author comments
• The -private flag tells javadoc to
document private, package, and protected
items as well as public ones
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
The End