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.