It would be useful to add a doc-comment tag that translates into the appropriate
target code an entry for an alphabetic index.
The syntax might be something like:
@index user interface:layout
would generate index output such as:
creating . . . . . . . . . . . . . 7
modifying . . . . . . . . . . . . 12
layout . . . . . . . . . . . . . . 9
The page numbers would appear only on printed documentation (PDF),
as generated by the MIF doclet.
Note that ":" is the argument separator. To allow index entries to contain a literal ":" character, there must be a means for escaping or overriding the argument separator.
Unless a sensible translation can be determined, the @index tag probably should just be ignored when generating straight HTML output.
When trying to comprehend any new API, it is difficult to locate classes,
etc. except by scrolling through package trees, etc. It would be nice if
the JavaDoc HTML output contained an Index frame with plain English entries
that would help those unfamiliar with various APIs and packages find their
way around. I suggest that some sort of tag be developed that uses the
same conventions as in the FrameMaker marker dialogue, including either
HTML or FrameMaker format builders and directives, that is
@ix main level1entry:<i>level2entry</>:level3entry[main
@ix cats:feeding of;<$nopage>canines. <EmphasisItalic>See<Default Para
So instead of trying to wallow through pages of class/package lists looking
for the my.packg.nested.deeply.BusCust class, I could just look up
"business customer class" in the Index and go to the (printed) page or
click to go to the (html) page.
Studies have repeatedly shown that a reader confronted with an unfamiliar
document will go to the table of Contents to learn about the general scope
of the content, but thereafter always goes to the Index.
NOTE: 4100717 was closed as a duplicate
###@###.### 10/20/04 17:04 GMT