JDK-4748246 : Doclet API: Doc.position() needs clarification
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.0
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2002-09-16
  • 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: eaT66865			Date: 09/16/2002

Doc.position() says it returns null "if no position is
available". The conditions under which that may be true
need to be documented.

Neal wrote: A default constructor will return null, because
    it has no location in the source file.

The comment also says it returns "the source position of the
documented entity".

To me, that read as "first line of the comment", which is
hopelessly wrong. A sentence which is less open to misinterpretation
would be helpful. Maybe: "The position in the source file of
the first line of the declaration for the program element that the
comment documents." (Accurate, but verbose. Shorter would be better.)


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

WORK AROUND Name: eaT66865 Date: 09/16/2002 ======================================================================

PUBLIC COMMENTS Clarified by changing it to: /** * Return the source position of the first line of the * corresponding declaration, or null if * no position is available. A default constructor returns * null because it has no location in the source file. */ SourcePosition position(); This bug fix has no regression test, as it affects only doc comments. ###@###.### 2002-10-03

EVALUATION Fixed as suggested. ###@###.### 2002-10-03