Embed Size (px)
Citation preview
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 specially-written “javadoc comments” and include them in its documentation
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
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 -d dir *.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
The -d flag names an existing directory for output
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
