JDK-4763596 : Doclet API: Further clarify occurrences of "class"
  • 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-10-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.
Other
1.4.2 mantisFixed
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
14-06-2004

WORK AROUND Name: dk30142 Date: 10/15/2002 ======================================================================
11-06-2004

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
21-10-2002

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
15-10-2002