[vector] java doc for iota()

[Paul Sandoz]

Hi Sandhya,

How about this:

diff -r 4e1b42f04b63 src/jdk.incubator.vector/share/classes/jdk/incubator/vector/VectorShuffle.java
--- a/src/jdk.incubator.vector/share/classes/jdk/incubator/vector/VectorShuffle.java    Fri Nov 15 16:13:16 2019 +0800
+++ b/src/jdk.incubator.vector/share/classes/jdk/incubator/vector/VectorShuffle.java    Mon Nov 18 12:59:22 2019 -0800
@@ -346,14 +346,19 @@
      * 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.
+     * <p>
+     * If {@code wrap} is false each index is validated
+     * against the species {@code VLENGTH}, and (if invalid)
+     * is partially wrapped to an exceptional index in the
+     * range {@code [-VLENGTH..-1]}.
+     * Otherwise, 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]}.
      *
      * @apiNote The {@code wrap} parameter should be set to {@code
      * true} if invalid source indexes should be wrapped.  Otherwise,
diff -r 4e1b42f04b63 src/jdk.incubator.vector/share/classes/jdk/incubator/vector/VectorSpecies.java
--- a/src/jdk.incubator.vector/share/classes/jdk/incubator/vector/VectorSpecies.java    Fri Nov 15 16:13:16 2019 +0800
+++ b/src/jdk.incubator.vector/share/classes/jdk/incubator/vector/VectorSpecies.java    Mon Nov 18 12:59:22 2019 -0800
@@ -645,14 +645,19 @@
      * 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 shuffleFromOp(i -> R(start + i * step))},
      * where {@code R} is {@code wrapIndex} if {@code wrap} is true,
      * and is the identity function otherwise.
+     * <p>
+     * If {@code wrap} is false each index is validated
+     * against the species {@code VLENGTH}, and (if invalid)
+     * is partially wrapped to an exceptional index in the
+     * range {@code [-VLENGTH..-1]}.
+     * Otherwise, 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]}.
      *
      * @apiNote The {@code wrap} parameter should be set to {@code
      * true} if invalid source indexes should be wrapped.  Otherwise,


Thanks,
Paul.

> 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