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

[Chris Hegarty]

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.
>