RFR 8020061: Clarify reporting characteristics between splits

[Chris Hegarty]

Sorry Paul, I know the apiNote says "for examples see ..." but would you 
mind providing an example. I'm scratching my head.

-Chris.

On 10/08/2013 12:42 PM, Paul Sandoz wrote:
> Hi,
>
> The following patch is a minor clarification to the documentation of Spliterator.characteristics():
>
>    http://hg.openjdk.java.net/lambda/lambda/jdk/rev/653d17f35169
>
> Paul.
>
> --- a/src/share/classes/java/util/Spliterator.java	Tue Oct 01 12:10:04 2013 +0200
> +++ b/src/share/classes/java/util/Spliterator.java	Tue Oct 08 13:36:27 2013 +0200
> @@ -414,12 +414,18 @@ public interface Spliterator<T> {
>        * #ORDERED}, {@link #DISTINCT}, {@link #SORTED}, {@link #SIZED},
>        * {@link #NONNULL}, {@link #IMMUTABLE}, {@link #CONCURRENT},
>        * {@link #SUBSIZED}.  Repeated calls to {@code characteristics()} on
> -     * a given spliterator should always return the same result.
> +     * a given spliterator, prior to or in-between calls to {@code trySplit},
> +     * should always return the same result.
>        *
>        * <p>If a Spliterator reports an inconsistent set of
>        * characteristics (either those returned from a single invocation
>        * or across multiple invocations), no guarantees can be made
>        * about any computation using this Spliterator.
> +     *
> +     * @apiNote The characteristics of a given spliterator before splitting
> +     * may differ from the characteristics after splitting.  For specific
> +     * examples see the characteristic values {@link #SIZED}, {@link #SUBSIZED}
> +     * and {@link #CONCURRENT}.
>        *
>        * @return a representation of characteristics
>        */
>