On 6 Jan 2014, at 18:11, Chris Hegarty <chris.hega...@oracle.com> wrote:
> On 6 Jan 2014, at 17:05, Martin Buchholz <marti...@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.
>
