Re: EnumSet and varargs

From:

Piotr Kobzda <pikob@gazeta.pl>

Newsgroups:

comp.lang.java.programmer

Date:

Thu, 18 Sep 2008 23:56:03 +0200

Message-ID:

<gauiq2$k1a$1@inews.gazeta.pl>

Mark Space wrote:

Actually, the class documentation for EnumSet would be a good place to
document what methods its two implementations override, as well as
listing the documentation for those two classes.

Better solution IMHO, would be addition of abstract methods to EnumSet
documenting behavior implemented in its private subclasses (where
reasonable of course).

For example:

     /**
      * Adds the specified element to this set if it is not already present.
      *
      * @param e element to be added to this set
      * @return <tt>true</tt> if the set changed as a result of the call
      *
      * @throws NullPointerException if <tt>e</tt> is null
      */
     public abstract boolean add(E e);

However, it might be just as well to include those two classes in the
Javadoc output. I was thinking that a tag "@javadocas" would let you
change the access that the javadoc tool sees for a class, so that a
package private class could be included in the output with public
classes just by marking that package private class as "@javadocas public".

I don't think it's necessary. The source code is shipped with JDK, so
Java doc for non public API may easily be generated (javadoc -private ...).

Unfortunately, it won't help a tool correctly prompt each use of the API.

piotr