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 zBesides producing professional-looking documentation, javadoc also has these advantages yBecause the program documentation is right in the program itself, it's much easier to keep it up to date y It's easy to recreate the documentation when the program is changed yWhen 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 zSun's Java API (Application Programmer's Interface) is a wonderful resource zKeep 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 zHere’s what it looks like:

6. javadoc comments  Ordinary comments: /* any text */  javadoc comments: /** any text */ z/** Single line comments are like this */ z/** * Multi-line comments are usually * written like this; the stars at the * front of lines are ignored. */

7. What can be commented zYou can use javadoc comments for yclasses yfields (variables) ymethods yconstructors yinterfaces  javadoc ignores internal comments (in front of statements, blocks, etc.)

8. Placement of javadoc comments zYou can put a javadoc comment immediately before a class, field, method, constructor, or interface zNothing but whitespace can come between a javadoc comment and the thing being commented zBadly placed javadoc comments are ignored

9. Examples z/** This is a comment for variable max */ double max; double min; /** This comment is for avg */ double avg; z/** This comment is ignored. */ // class Something {... }

10. HTML in javadoc zIf you know HTML, you can put some HTML commands in javadoc comments zYou can use bold, italic, paragraph, various kinds of lists, hypertext links, images, etc.  You can not use document structuring commands, such as,, or

11. Special tags  Special tags begin with @ and must be the first thing on the line zTags are used for describing parameters, return types, related methods, etc.  You should always use the @author tag for class assignments zExample:  @author John Q. Student

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

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