Name: rm29839 Date: 10/30/97

This situation occurs over and over:
  1. There is an @param tag for options.
  
  2. There is a YES_NO_OPTION and a YES_NO_CANCEL_OPTION.
  
  3. Those are the options that exist today. In the future, additional
     options are likely to be added.
     
The API comment for the method with this parameter needs to provide
an @see link to the possible options. Note that:
  * If you list the possible options in the comment, you KNOW the list
    will be out of date as soon as someone adds an additional option.
    
  * If you don't provide a list or a link, the user has to make the
    connection between which of several sets of constants defined in
    the file apply to any given tag. No one link is hard, but the
    collection of all of them begins to impose a significant burden.
    
Again, the issue comes back to the ability to modularize the documentation.
We need to link to a location, where the contents of that location are
determined by javadoc.

Currently, files are linear. We have option1, option2, option3, etc.
What we need is hierarchy. So we can have:
   CATEGORY
      option1
      option2
      option3
      
Then both individual entries and common elements can be indexed and linked.
     
This is exactly the same issue as:
   PROPERTY
      getProperty
      setProperty
      isProperty

(Individual options need to link to the Category discription automatically,
or else be physically adjacent so it is easy to find.)

eric
(Review ID: 14803)
======================================================================