JDK-4502589 : Doclet API: misleading documentation for "kind" in com.sun.javadoc.Doc
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.2.2
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2001-09-13
  • Updated: 2014-05-05
  • Resolved: 2002-10-26
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
1.4.2 mantisFixed
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) 

CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: mantis FIXED IN: mantis INTEGRATED IN: mantis mantis-b05

EVALUATION Changed synopsis from: Specific documentation bug in com.sun.javadoc.Doc to: Doclet API: misleading documentation for com.sun.javadoc.Doc

WORK AROUND Name: bsT130419 Date: 09/13/2001 Write a few toy doclets. Play around until it sits straight in your head. ======================================================================

PUBLIC COMMENTS Fixed as suggested. No regression test included because this is a doc comment only change. ###@###.### 2002-09-28