[vector] java doc for iota()

[John Rose]

The intention here is that every shuffle is either partially or fully wrapped.
This means that the lane size of a shuffle is 1+ceil(lg(VLENGTH)), where
the 1 encodes the optionally present “partial wrap” state.  My goal here
is that shuffles are never used as side channels for additional information,
either intentionally or otherwise.  So even if a shuffle has “more bits”
in it, and those bits are not normalized, no operation on a shuffle can
reveal those bits.

> On Nov 12, 2019, at 2:53 PM, Viswanathan, Sandhya <sandhya.viswanathan at intel.com> wrote:
> 
> Hi Paul,
> 
> There is another place, where the java doc may need to change.
> 
> The Java implementation of iota() performs full wrapping when "wrap" is passed as true, otherwise it does partial wrapping.
> Whereas the java doc below in VectorShuffle.java doesn't mention partial wrapping at all:
>    /**
>     * Creates a shuffle using source indexes set to sequential
>     * values starting from {@code start} and stepping
>     * by the given {@code step}.
>     * If {@code wrap} is true, also reduce each index (as if
>     * by {@link VectorShuffle#wrapIndex(int) wrapIndex})
>     * to the valid range {@code [0..VLENGTH-1]}.
>     * <p>
>     * This method returns the value of the expression
>     * {@code VectorShuffle.fromOp(species, i -> R(start + i * step))},
>     * where {@code R} is {@code wrapIndex} if {@code wrap} is true,
>     * and is the identity function otherwise.
>     * ......
>     */
> public static <E> VectorShuffle<E> iota(VectorSpecies<E> species,
>                                            int start, int step,
>                                            boolean wrap) {
> 
> There is mention of partial wrapping in java doc of fromValues in VectorShuffle.java:
>    *
>     * <p> For each shuffle lane, where {@code N} is the shuffle lane
>     * index, the {@code N}th index value is validated
>     * against the species {@code VLENGTH}, and (if invalid)
>     * is partially wrapped to an exceptional index in the
>     * range {@code [-VLENGTH..-1]}.
> 
> Best Regards,
> Sandhya
> 
>