United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4763596 : Doclet API: Further clarify occurrences of "class"

Details
Type:
Bug
Submit Date:
2002-10-16
Status:
Resolved
Updated Date:
2014-05-05
Project Name:
JDK
Resolved Date:
2002-10-26
Component:
tools
OS:
generic
Sub-Component:
javadoc(tool)
CPU:
generic
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.4.0
Fixed Versions:
1.4.2 (mantis)

Related Reports

Sub Tasks

Description
Name: dk30142			Date: 10/15/2002


Many of the Doclet API descriptions have been modified
to be more clear. Some problems remain, though.

  (1) Reviewing the index, I see that ClassDoc has constructors()
      method as the first thing. Another reason you'd never even
      *think* to check isClass() on a ClassDoc object.

      What does it return for an interface, anyway?

  (2) There are also fields() methods, which must return null for an
       interface. It says it returns the fields in this interface. I didn't
       know an interface could define fields. I don't *think* it can,
       but I could be wrong...

  (3) Similarly for isAbstract(). Returns true for an interface?

  (4) Also subClassOf() and superClass(). They need to describe
      their behavior for an interface.

      (Basically, I think the large number of class-specific methods
       points out why "class" should never have been used to mean
       "class or interface". *We* can't even keep it straight. I know
       for sure I can't when I'm using the APIs.)

  (5) For methods(), the doc reads "Return included methods in this
      class or interface.". But the phrase "included methods" starts
      out like its going to say "included packages", and then ends in
      an unfamiliar phrase. I'd be inclined to rewrite as "Return
      methods defined in this class or interface." Or use the text
      in the methods (boolean) description.

                                    

Comments
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
mantis

FIXED IN:
mantis

INTEGRATED IN:
mantis
mantis-b05


                                     
2004-06-14
WORK AROUND



Name: dk30142			Date: 10/15/2002



======================================================================
                                     
2004-06-11
PUBLIC COMMENTS

Fixed doc comments as described in the evaluation.
No regression test required, as this affects only the doc comments
with no change to the API spec.
###@###.### 2002-10-21
                                     
2002-10-21
EVALUATION

To answer your questions in Comments, based on the language

(1) Interfaces may have no constructors.
(2) Interfaces may have constant fields.
(3) Interfaces are always abstract, but
    I'm not sure if this flag set for them in javadoc.
(4) Interfaces in the language have no superclass
    but in the VM they have Object as a superclass.
    Check to see which rule javadoc follows.
(5) Sure.

By the way, the convention is to use "Description" to describe the specific
problem being reported, and "Comments" for Sun-private information.

###@###.### 2002-10-15

I tested this and have done the following:
(1) Added statement that for interfaces, constructors() returns an empty array.
(2) Nothing further to clarify.
(3) isAbstract() for an interface returns true.  Added this note.
(4) superclass() for an interface is null
    subclassOf(rootdoc.classNamed("java.lang.Object")) for an interface is true
    Documented these.
    Note this contradiction:  while all interface have no superclass, 
    they are all subclasses of Object.
    Neal says:
    I think we cannot change this behavior.  This is inherited from the language 
    and VM specifications, and I would not be surprised if existing doclets 
    depend on this behavior.
(5) methods() only returns the *included* methods, so didn't change the 
    wording.  Added link to the definition of "included" and added
    "Same as methods(true)."

###@###.### 2002-10-15
                                     
2002-10-15



Hardware and Software, Engineered to Work Together