|
Description
|
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)
======================================================================
|
