JDK 9 RFR - 8031142 [was: Re: Using @implSpec in AbstractMap, AbstractCollection, AbstractList, etc]

[Martin Buchholz]

   - JDK <https://bugs.openjdk.java.net/browse/JDK>
   - JDK-6270645 <https://bugs.openjdk.java.net/browse/JDK-6270645>

Javadoc comments should be inherited from most derived superinterface or
superclass

   -

but that's marked fixed...


On Mon, Jan 6, 2014 at 12:49 PM, Chris Hegarty <chris.hegarty at oracle.com>wrote:

>
> On 6 Jan 2014, at 18:11, Chris Hegarty <chris.hegarty at oracle.com> wrote:
>
> > On 6 Jan 2014, at 17:05, Martin Buchholz <martinrb at google.com> wrote:
> > ……..
> >>
> >> In a sane language, the AbstractFoo classes would be traits - they
> should never contribute to the *specification* of a concrete class, only to
> its implementation.  Therefore,  in Java, all of the methods should have
> precisely an {@inheritDoc} followed by an @implSpec.  In particular, for
> AbstractCollection.toArray I see:
> >>
> >> 114     /**
> >> 115      * {@inheritDoc}
> >> 116      *
> >> 117      * <p>This method is equivalent to:
> >> 118      *
> >> 119      *  <pre> {@code
> >> 120      * List<E> list = new ArrayList<E>(size());
> >> 121      * for (E e : this)
> >> 122      *     list.add(e);
> >> 123      * return list.toArray();
> >> 124      * }</pre>
> >> 125      *
> >> 126      * @implSpec
> >> 127      * This implementation returns an array containing all the
> elements
> >> 128      * returned by this collection's iterator, in the same order,
> stored in
> >> 129      * consecutive elements of the array, starting with index
> {@code 0}.
> >> 130      * The length of the returned array is equal to the number of
> elements
> >> 131      * returned by the iterator, even if the size of this
> collection changes
> >> 132      * during iteration, as might happen if the collection permits
> >> 133      * concurrent modification during iteration.  The {@code size}
> method is
> >> 134      * called only as an optimization hint; the correct result is
> returned
> >> 135      * even if the iterator returns a different number of elements.
> >> 136      */
> >> 137     public Object[] toArray() {
> >>
> >> which must be wrong.  Either the sample code should be moved into the
> @implSpec or promoted to Collection.java.toArray.  The introduction of
> default methods ("not quite traits") makes the situation murkier.  Looking
> more closely, the exact wording cannot be promoted to Collection.java
> because the behavior may in fact differ from the code sample.  size() may
> or may not be called.  toArray implementation is more likely to be atomic,
> etc...  So move it into the @implSpec somehow…
>
> Done.
>
> >
> > I wasn’t quite sure about this. “This method is equivalent to, or, as if
> the following was invoked …” without actually specifying the actual
> implementation. But I agree, AbstractFoo should only have @inheritDoc or
> @implSpec. Let me see what happens when I move it into @implSpec.
>
> Updated webrev and spec diff:
>
> http://cr.openjdk.java.net/~chegar/8031142/specdiff.01/overview-summary.html
>   http://cr.openjdk.java.net/~chegar/8031142/webrev.01/webrev/
>
> AbstractList retains its copy of the List add(E), clear(), and iterator()
> method specifications. When I replaced them with {@inheritdoc}, the
> Collection/AbstractCollection docs were copied in ( but we want the List
> docs ). I think this is a javadoc bug. I’ll look into this separately.
>
> -Chris.
>
> >
> > -Chris.
> >
>
>