JDK-4034228 : stddoclet: Add @index doc-comment tag for generating an index from common words
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.1,1.2.0,1.2.2
  • Priority: P5
  • Status: Resolved
  • Resolution: Won't Fix
  • OS: generic,solaris_2.5.1,windows_95
  • CPU: generic,x86
  • Submitted: 1997-02-24
  • Updated: 2014-05-05
  • Resolved: 2013-12-12
Related Reports
Duplicate :  
Duplicate :  
Relates :  
Description
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 entry[:sub-entry]...

For example:

@index database:creating
@index database:modifying
@index user interface:layout

would generate index output such as:

       database
            creating . . . . . . . . . . . . .  7
            modifying  . . . . . . . . . . . . 12
       user interface
            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
leveloneentry:leveltwoentry:levelthreeentry];another entry
     @ix cats:feeding of;<$nopage>canines. <EmphasisItalic>See<Default Para
Font> dogs

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

Comments
The doclet provides a capability to implement custom tags. Anyone needing a new tag can implement the taglet interface and provide the correct command line options while generating javadoc pages, to use the tag.
12-12-2013

SUGGESTED FIX The most general solution is to allow index entries to be both in-line and standalone tags. It would be good to allow the richness of Framemaker indexing, which allows indented subentries. Alternative solutions: 1) As shown in the description part of this bug, this will work both as a standalone and in-line tag: Standalone tag format: FORMAT: @index entry[:sub-entry]... EXAMPLE: @index addItem:Choice In-line tag format FORMAT: {@index entry[:sub-entry]...} EXAMPLE: {@index addItem:Choice} 2) RFE 4100717 recommends using the HTML name tag, which could only be used in-line: <a name="foo"></a>
11-06-2004

PUBLIC COMMENTS
10-06-2004

EVALUATION Low priority at this point. Others can implement it in the templates for themselves. doug.kramer@Eng 1997-10-07 Won't implement for 1.2 doug.kramer@Eng 1998-04-03 Low priority, but do if trivial for 1.2.2. doug.kramer@Eng 1998-12-15
07-10-1997