United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4502589 Doclet API: misleading documentation for "kind" in com.sun.javadoc.Doc
JDK-4502589 : Doclet API: misleading documentation for "kind" in com.sun.javadoc.Doc

Details
Type:
Bug
Submit Date:
2001-09-13
Status:
Resolved
Updated Date:
2002-10-26
Project Name:
JDK
Resolved Date:
2002-10-26
Component:
docs
OS:
generic
Sub-Component:
doclet
CPU:
generic
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.2.2
Fixed Versions:
1.4.2 (mantis)

Related Reports

Sub Tasks

Description
Name: bsT130419			Date: 09/13/2001

java version "1.3.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.0-C)
Java HotSpot(TM) Client VM (build 1.3.0-C, mixed mode)


There is a specific documentation bug in the documentation for
com.sun.javadoc.Doc.inlineTags() and com.sun.javadoc.Doc.firstSentenceTags().

Doc comment for both methods says:
"...Inline tags are represented as a SeeTag of kind "link"..."

Firstly, the term "kind" is undefined -- assuming it is the
com.sun.javadoc.Tag.kind() method.

Assuming that the term "kind" refers to the Tag.kind() method metioned above:
The comment is then incorrect. A SeeTag representing an inline {@link ...} tag
has kind() equal to "@see", just like your average SeeTag does.
The method that is meant by this cryptic doc comment is, I believe, Tag.name().
This returns "@see" for a SeeTag representing a '@see' doc comment, and
returns "@link" for a SeeTag representing a '{@link ...}' doc comment.

Even by correcting the term "kind" to "Tag.name()", the comment would be
incorrect, because the return value of both Tag.kind() and Tag.name() contains
the '@' symbol, although the comment above implies the opposite, namely that
the '@' symbol is omitted!
(Review ID: 131811) 
======================================================================

                                    

Comments
PUBLIC COMMENTS

Fixed as suggested.
No regression test included because this is a doc comment only change.

###@###.### 2002-09-28
                                     
2002-09-28
WORK AROUND



Name: bsT130419			Date: 09/13/2001


Write a few toy doclets. Play around until it sits straight in your head.
======================================================================
                                     
2004-06-11
EVALUATION

Changed synopsis from:
  Specific documentation bug in com.sun.javadoc.Doc
to:
  Doclet API: misleading documentation for com.sun.javadoc.Doc
                                     
2004-06-11
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
mantis

FIXED IN:
mantis

INTEGRATED IN:
mantis
mantis-b05


                                     
2004-06-14



Hardware and Software, Engineered to Work Together