Java Cookbook

Documenting Classes with Javadoc

Problem

You have heard about this thing called " code reuse,” and would like to promote it by allowing other developers to use your classes.

Solution

Use Javadoc.

Discussion

Javadoc is one of the great inventions of the early Java years. Like so many good things, it was not wholly invented by the Java folk; earlier projects such as Knuth’s Literate Programming had combined source code and documentation in a single source file. But the Java folk did a good job on it and came along at the right time. Javadoc is to Java classes what manpages are to Unix or Windows Help is to MS-Windows applications: it is a standard format that everybody expects to find and knows how to use. Learn it. Use it. Write it. Live long and prosper (well, perhaps not). But all that HTML documentation that you refer to when writing Java code, the complete reference for the JDK -- did you think they hired dozens of tech writers to produce it? Nay, that’s not the Java way. Java’s developers wrote the documentation comments as they went along, and when the release was made, they ran Javadoc on all the zillions of public classes, and generated the documentation bundle at the same time as the JDK. You can, should, and really must do the same when you are preparing classes for other developers to use.

All you have to do to use Javadoc is to put special " doc comments” into your Java source files. These begin with a slash and two stars ( /**), and must appear immediately before the definition ...