On 6 Jan 2014, at 17:05, Martin Buchholz <marti...@google.com> wrote:
> On Mon, Jan 6, 2014 at 8:47 AM, Chris Hegarty <chris.hega...@oracle.com> > wrote: > Part 2... > > JDK 9 RFR - 8031142: AbstractCollection and AbstractList should specify their > default implementation using @implSpec > > http://cr.openjdk.java.net/~chegar/8031142/webrev/ > http://cr.openjdk.java.net/~chegar/8031142/specdiff/ > > Is that specdiff link what you want? I just get a giant tree with javax > files in it... > > --- > > 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… 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. -Chris.
