Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
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