RFR 8022318: Document Spliterator characteristics and binding policy of java util concurrent collection impls

[Martin Buchholz]

Thanks, Paul.

I made a mistake with the anchor name in package-info.java.
s/WeaklyConsistent/Weakly/
Fix is already in latest jsr166.  Resync package-info.java.
Else looks good.

TODO: all collection class documentation referring to iterators needs to be
examined to check whether it needs to be updated to refer to "iterators and
spliterators".


On Mon, Aug 12, 2013 at 5:22 AM, Paul Sandoz <paul.sandoz at oracle.com> wrote:

> Hi,
>
> The following patch updates documentation for various spliterators in the
> j.u.concurrent package:
>
>
> http://cr.openjdk.java.net/~psandoz/tl/JDK-8022318-concurrent-split-docs/webrev/
>
> This syncs from the 166 repo and the documentation is just clarifying
> stuff that was missing.  Many thanks to Martin for helping out with this.
>
> There are a few additional tweaks here and there that are included, the
> only non-formating/non-documentation tweak is to
> SynchronousQueue.iterator():
>
> -    @SuppressWarnings("unchecked")
>      public Iterator<E> iterator() {
> -        return (Iterator<E>) EmptyIterator.EMPTY_ITERATOR;
> -    }
> -
> -    // Replicated from a previous version of Collections
> -    private static class EmptyIterator<E> implements Iterator<E> {
> -        static final EmptyIterator<Object> EMPTY_ITERATOR
> -            = new EmptyIterator<Object>();
> -
> -        public boolean hasNext() { return false; }
> -        public E next() { throw new NoSuchElementException(); }
> -        public void remove() { throw new IllegalStateException(); }
> +        return Collections.emptyIterator();
>      }
>
> Paul.