United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4748246 Doclet API: Doc.position() needs clarification
JDK-4748246 : Doclet API: Doc.position() needs clarification

Details
Type:
Bug
Submit Date:
2002-09-16
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.4.0
Fixed Versions:
1.4.2 (mantis)

Related Reports

Sub Tasks

Description

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.)

======================================================================

                                    

Comments
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
                                     
2002-10-03
EVALUATION

Fixed as suggested.
###@###.### 2002-10-03
                                     
2002-10-03
WORK AROUND



Name: eaT66865			Date: 09/16/2002



======================================================================
                                     
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