Object-Oriented Enterprise Application Development Javadoc Last Updated: 06/30/2001

Topics This Javadoc overview examines: Purpose Javadoc tags Generating javadoc

Javadoc Comments

Purpose Javadoc is one of the tools that makes up Java. It's used to provide documentation at the point that it's most likely to be maintained; the source code.

Structure Javadoc is generated using a two (2) step process: Place the appropriate comments and tags within your Java source code Execute the javadoc utility.

Comments /** * All javadoc comments begin with a variation of * the multi-line edit. The only difference is * that it has two asterisks instead of just one. * * These comments will be ignored by the java * compiler, but will be used by javadoc to * generate the appropriate HTML documents. */

Tags While there are a variety of javadoc tags, there are only a few that we @throws

Sample (1 of 2) package sample; /** * This class is used to illustrate the basic concepts of * javadoc. If this were "real" javadoc, then this text would * go into some detail about what exactly this class was for * and how another developer would use it. * Chris Jones * 1.0 */ public class Sample {

Sample (1 of 2) /** * The javadoc should provide details about what this method * does really, including any preconditions, postconditions, * and other information another developer might need. * arg1 Describe what the argument is for, any * limitations on its value, etc. You'll have one of these * tags for each parameter passed to the method. * Describe what the return value represents. * Describe each exception thrown by the method. * You'll have one of these tags for each type of exception * identified by the method's throw clause. */ public int doStuff(int arg1) throws Exception { // TODO: whatever needs doing.... }

Tags Obviously you might not need all of the tags for each method within the class. For example, if the method doesn't throw an exception, then you wouldn't use tag. Use only those tags that make sense.

Javadoc Generation

Utility Once the javadoc has been written into your code, you can generate the associated HTML using the javadoc utility. Javadoc, like java, javac, and jar, is located in your \bin directory. This utility works best when your source code is placed into directory structures that mirror your packages.

Utility (2 of 2) Javadoc has many optional arguments. To see them and experiment, just type javadoc from the command line It isn't necessary to have compiled the.java files before using javadoc.

Utility (2 of 3) For this class, most of the default settings are fine: javadoc –d For example: javadoc –d javadoc sample