I have been using Javadoc feature of package comments to avoid littering source code with verbose documentation comments.
With Javadoc 1.2, package-level doc comments are available. Each package can have its own package-level doc comment source file that The Javadoc tool will merge into the documentation that it produces. This file is named
package.html (and is same name for all packages). This file is kept in the source directory along with all the
*.java files. (Do not put the
packages.html file in the new doc-files source directory, because those files are only copied to the destination and are not processed.)
The file package.html is an example of a package-level source file for
java.text and package-summary.html is the file that the Javadoc tool generates.
The Javadoc tool processes
package.html by doing three things...
Using above feature, I had detailed verbose documentation for classed and methods in the package stored separately of code, in a dedicated html file. As for javadoc comments in java files, I just wrote brief explanations there, adding text like
If needed, refer to package documentation for more details.
One thing I particularly liked about this was that although docs were in the separate file and in a format more convenient for large docs (html), it has been stored close enough to related source code and all the updates in it were automatically picked up during the build.
Starting from Java 1.5, you can alternatively put a
package-info.java along with the classes of the package. This file should look like this:
* Javadoc for your package here
See more details in this stackoverflow question