Name: wl91122 Date: 07/13/99


I propose that a new tag is supported by the standard doclet, to classify classes or their features inside categories -- similar to the common practice in Smalltalk environments.

Example (for java.lang.String):

/**
 * Returns the index blah blah blah...
 *
 * @param ch a character.
 * @return the index of the last occurrence (...)
 * @category searching
 */
public int lastIndexOf(int ch) {...)

The class String has 8 methods that I would put in the "searching" category (all indexOf() and all lastIndexOf()). It would be much easier to browse this class if my editor could group the methods according to such categories. The same is good for attributes and even classes -- inside a single package you may have supporting classes, interfaces, test cases, factories and other categories, and it would be great to view "all test case classes" no matter which package.

Well, I guess the advantages are pretty well known from ST tradition.

This main use of categories is, of course, unrelated to the javadoc tool. IDE vendors are expected to implement the necessary support, which depends on some parsing. Class files compiled in debug mode could keep category information as new Attributes, these would be ignored by VMs (Java VM Spec, 4.7.1) so we could also browse sourceless binaries. But it's critical that such a feature is blesses by Javasoft as "official" so we don't lose the browsing capability when going from one editor to another. Of course each editor may chose to use the category data in a different way (a ST- inspired, 4-pane browser is not mandatory) or even to ignore it.

The javadoc tool would be using this tag, although it's not the main point in my proposal. It would be nicer to separate those long HTML streams into several topics, with the individual mathods and attributes as subtopics. We could have new navigation facilities like category indexes, or new documentation compilation facilities, e.g. exclude detailed docs (only summary, without parameters/return/since etc.) for all methods inside the "accessors" category, because they are well known and all the same. Manageable, useful documentation is documentation that's both well indexed, and not bloated / polluted by redundant information.
(Review ID: 85520)
======================================================================