Download javadoc

Survey
yes no Was this document useful for you?
   Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Document related concepts
no text concepts found
Transcript
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