Writing Javadoc Comments

     

Javadoc comments are an advanced form of comments. The purpose of regular source code comments is to indicate to readers of your source code files what you're up to. The limitation here is obvious.

What if I don't wanna distribute my source code files? Even if I did, it's inconvenient and difficult to sort through all of the source code just to find out what a class' contract is.

Then you have to distribute documentation files separately. Duh.

But it's a draaaag to make separate documentation files. They get out of synch with my source code, and then they're worse than useless.

True. You're starting to sound a little whiney, dear, but these are good points. Javadoc addresses your concerns by providing a facility for generating complete code documentation externally, in HTML. It's a terrific and easy documentation tool, because HTML is platform independent and anybody can view it with pleasure .

How to Do It

There are two requirements for generating documentation. First, you need to add the appropriate comments to your file. Second, you need to run the Javadoc command-line tool that creates the files.

The Javadoc tool generates documentation for the following items:

  • Packages

  • Public classes and interfaces

  • Public and protected methods

  • Public and protected fields

No private items are included unless you explicitly specify them.

Just write your special comments immediately above the items in your files that they comment (that is, right above your class, right above each field, and right above each method). All of your Javadoc comments must be outside a method body.

Start Javadoc comments with /** and end them with */ . Since Java 1.4, the two asterisks are not required, but are convention.

Write a short sentence summarizing a method, or a short paragraph or two to summarize a class.

Within your summary text, you can use the inline tag {@link URL } to have Javadoc create a hyperlink for you. You can also use any HTML tags you want, though it is typically kept to basic items such as <P> and <CODE> to format your comments.



Java Garage
Java Garage
ISBN: 0321246233
EAN: 2147483647
Year: 2006
Pages: 228
Authors: Eben Hewitt

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net