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. 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:

5. 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. */

6. 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.)

7. 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

8. 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 {... }

9. 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,, or

10. 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

11. 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

12. 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

13. The End