This must be coordinated with RFE 4287701.

Categories would be useful for all class/interface members.
Original description, which pertains only to static fields
is below:
-------------------
Categories are needed for static finals.
   ex: static final ints RED = 1, YELLOW=2, BLUE=3

Suppose I have a parameter int color, which is expected to take one
of these values. JavaDoc needs to be able to specify a category for
the possible colors, and include the colors in that catagory.

Robert suggest that the syntax should be:
   /** @category COLOR_VALUES */
   static final int RED = 1;
   /** @category COLOR_VALUES */
   static final int YELLOW = 2;
   /** @category COLOR_VALUES */
   static final int BLUE = 3;

The syntax is secondary (although the suggested synax seems clunky,
there is probably no good alternative until the day that compilers
can process XML files, at which point the category could be defined
as an XML heading that the compiler would conveniently ignore).

The important thing, though, is the ablity to point
to a range of values -- a category -- from within a javadoc comment.

Then (using embedded tags) you can write:
   * @param color An int that is one of the {@category COLOR_VALUES}

or (with normal @see tags):
   * @param color An int that is one of the COLOR_VALUES
   * @see COLOR_VALUES

NOTE: We might use @list or @cat or @use instead of @category,
since @category is obtrusively long.

The presence of categories solves several important problems:
  1. Eliminates inane api comments like /** The red color */ for
     every single static final that is already a self-defining term.
  [Doug: This is actually important for localized documentation.
   Therefore, @category tag should be in *addition* to the description,
   not in place of it.]

  2. Makes it possible to keep the api comments up to date as colors
     are added and removed.
  [Doug: True, which is useful for point 3 below.]

  3. Connects parameters to the set of intended values. At the moment
     static finals are usually unconnected to @param tags -- the developer
     has to guess which values are intended, because the values (RED, etc)
     are not included in the method's comments. But if the values _are_
     included in the comments, you get problem and an api that is hard to
     keep up to date.
  [Doug: Very useful.]

  4. [Added by Doug] Enables members to be grouped by category in the
     member summary in the documentation.

NOTES:
  * We need a mechanism to provide comments for the category as a whole.
    Doug suggests an additional CATEGORYTEXT tag. Any comments in it
    would presumably be added to the category comments (if any).
  [Doug: Might not be necessary if grouping members in the member summary]

  * In general, the category comments and list of items in the category should
    appear in some unique location, most probably at the end of the html
    file for the class. The {@category COLOR_VALUES} tag should then become
    a link to that location. That strategy makes it possible to add general
    category comments and is important for long value-lists, like the
    virtual keys in java.awt.event.
  [Doug: Prefer to group the members in the member summary]

  * Doug suggests that option to copy the list of values into the current
    location would also be valuable. There are two distinct styles of copying
    that would need to be supported, imo. One is a comma-separated list:
    "RED, YELLOW, GREEN". Such a list would not include category comments,
    and would be suited for short-lists in a param tag. The other style is
    an HTML-list:
       <general comments><ul>
          <li>RED
          <li>YELLOW
          <li>GREEN
       </ul>
    This style would be suitable for copying into the class description, for
    example.
  [Doug: Perhaps an inline tag {@insertCategory COLOR_VALUES}

  * The name "COLOR_VALUES" is a fairly good prototype. It follows the
    pattern <type>_VALUES where, in this case, the data type is "COLOR".
  [Doug: Perhaps this could be defined in the class comment (if it applies
   only to members of that class). It should also include a localizable
   name that would appear as a category heading, and could include a
   description. Perhaps the syntax could have three arguments:
   {@categoryHead COLOR_VALUES "Colors" "Colors that set the fill or border"}

  * To be determined is what happens to the entry that would
    currently be generated for an individual value like RED.

    At the moment, the entry RED goes into the javadoc index, and
    it links to the description: "The color Red." But if RED is
    in the COLOR_VALUES category, then it might not have any
    text associated with it. If not, then RED should probably link
    to the html header for the COLOR_VALUES topic.
  [Doug: The RED index entry should link to the RED field, as usual]

  * In some cases, it would also be valuable to add an additional comment
    to a topic. For example:
       /**
        * The backspace key.
        * @category KEY_VALUES
        */
       static final int VK_BKSP ...
   
    In this trumped-up example, the abbreviation "BKSP" is not quite as
    self-evident as the other key names, so it needs some explanation.
    Now the index entry for VK_BKSP needs to link to a topic for that
    key, which must in turn include a link to KEY_VALUES.