Wednesday, December 18, 2002

Add main() documentation to JavaDoc

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.

2 comments:

Bruce Wallace said...

No, we have nothing in the works for this. You're welcome to submit a feature request following the features at: http://java.sun.com/j2se/javadoc/faq/index.html#submitbugs
-Doug Kramer (douglas.kramer@sun.com)

Bruce Wallace said...

Just to chime in here: That's a heck of an interesting idea, Bruce.

Since one strategy for unit testing is to include main() methods that run internal tests, such pages could document how the tests are run. (To keep from obscuring the main() method(s) that classe
that are supposed to be published could be named on the javadoc command line, instead of naming the packages.)

Mostly, though, I think that what you're talking could be implemented as a specialized doclet that only processes main() methods, or something of that sort.

The existing doclets are currently being refactored to produce a utility library that would make a doclet of that kind fairly easy to produce.

I'm curious to see what kind of specific proposals you might have in mind.
- eric armstrong (eric.armstrong@sun.com)
2/18/2002