Open Letter to JavaDoc group at Sun...
There is a major aspect of Java programming that JavaDoc does not cover, and that is documenting standalone programs; i.e. main() methods.
The reason simply adding JavaDoc comments to main() is not sufficient, is that while the program may be implemented inside some internal package, running the program from the outside world's perspective is a public thing.
There needs to be an "Applications" section up top in the overview page along with the packages summary. In this section, all main() methods that are being "published" can document their calling sequence (aka command line parameters), the formats of any input and output files, the list of and meaning of the process exit codes, and generally anything that all programs need to document such that the outside world knows how to use them.
In the Unix world, these things were in "man" pages. Java needs a standard, platform invariant, way to publish the same info via the JavaDoc mechanism.
I would be interested in following up with you to develop specific proposals, but at this point I simply wanted to register the need with you and see if any efforts were already in the works.