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  customer  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  customer  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. 

N/A

This is a useful feature.
After talking this over with Robert and Eric, Robert concluded
this should be implemented by adding an @category (or whatever)
tag to each of the static field doc comments, rather than
creating a new paradigm of start/end tags.  It would
look like this:

   /** @category COLOR_VALUES */
   static final int RED = 1;

   /** @category COLOR_VALUES */
   static final int YELLOW = 2;

   /** @category COLOR_VALUES */
   static final int BLUE = 3;

(Or use "COLOR" instead of "COLOR_VALUES")
  xxxxx@xxxxx   1998-03-17

This would also apply to methods and other members. It would take a great 
deal of thought to come up with a useful, scalable, consistent system 
for categorizing methods.  This RFE is practically a dupe of 4287701,
so they must both be solved together.
  xxxxx@xxxxx   2001-03-01

Changed synopsis from:
  stddoclet?: Introduce class member categories - e.g. @category 

  stddoclet: Introduce member categories - e.g. @category tag
  xxxxx@xxxxx   2002-03-25

This would be useful now, but please make sure this would not be
"legacy" if enumerations are to be added to the language in the near
future.  Of course, they still may be useful for collections of bitflags (and
I'm sure other things I haven't thought of).

This tag seems to be tied very closely to the use of families of static final constants as surrogates for C enums; 
this is a very bad practice in an OO language, and giving it a tag all to itself would seem to be condoning it.

ps sorry to play the style-fascist here!

There is a much more useful purpose for a tag like 
@category than to list enumeration values. A more pressing 
need is to group methods into logical categories for 
documentation purposes.
Consider a class that implements dozens of methods, and 
perhaps inherits many more. Currently, javadoc just lists 
them alphabetically at the top of the page. That is not 
very helpful when you are trying to first learn about the 
class.

An improvement would be to list method names, grouped by 
categories. The best example I know of this is in the 
WebObjects documentation from Apple, for an example see the 
section labelled "Method Types" 
http://developer.apple.com/techpubs/webobjects/System/Librar
y/Frameworks/WebObjects.framework/Java/Classes/WOComponent.h
tml
If you take a look at this documentation style, you will 
see how useful this section is compared to the stuff that 
javadoc produces, especially to someone new to the class. 
Once you understand a class well, the alphabetically sorted 
list is fine for reference. But its a lousy way to guess 
which methods are critical, and which ones one are the 
extra frills.

To get similar features in Javadoc, we could just label 
methods with lines such as @category printing or @category 
layout or @category state management. Then a doclet could 
generate an intro section with category names followed by 
links to the methods related to that category.

This lets a programmer quickly focus on the methods for the 
current task, rather than try to guess from the names.

I'd like to add my support for this proposed tag.  I agree 
with the comments made by "wabjr" relating to the point 
that this enhancement's usefulness is far more general than 
the original poster's scenario.

I've long wished that there were a tag called "@protocol" 
which would allow me to assign each method to a named 
logical group of related methods.  I won't quibble about 
whether "@protocol" is better than "@category" - either way 
it's useful.

I admit that my desire for this feature is in part driven 
by my heritage as a Smalltalk programmer.  Several of the 
Smalltalk code browsers have a "protocol" pane that allows 
the list of all methods implemented by a class to be 
filtered by "protocol".  It turns out that this is a 
simple, yet extremely useful, feature.  It would be no less 
useful in the context of Java - be it for organizing 
Javadoc or including a similar feature in some Java code 
browser.

Here are a few examples of typical protocols we used to 
use, along with a description of the kinds of methods that 
would be assigned to the protocol:

 "accessing" - getter and setter methods

 "converting" - methods that convert the object to another 
type (e.g., toInteger, toDate, toPolygon)

 "calculating" - methods that are about computation (e.g., 
calculateOrderTotal, calculateAverageDuration)

 "initializing" - methods that do initialization

 "adding/removing" - methods that add to or remove from a 
collection maintained by an object (e.g., addCustomer, 
removeOrder)

 "testing" - methods that query the state of the object 
(e.g., isConfirmed, isDirty, includesCustomer)

 "actions" - methods that command an object to do something 
(e.g., turnRight, closeConnection)

In addition to assisting in organizing Javadoce, having 
support for a @category or @protocol tag might encourage 
some vendors with Java code browsers to add by-category 
filtering of methods.  The closer we can get to a Smalltalk 
code browser, the more productive we will all be (my $0.02).

I have just looked in the javadoc help for a tag that
allows me to specify a category for methods in the sense
described by dmuirhead. I couldn't find one, and have
arrived here because I decided to check the list of
proposed tags.
I am not keen on using it for enumerations, since
that problem is solved in a much better way by the
typesafe enum pattern.

Great proposal. Please add this. Longing for categories from
the Smalltalk days...