RFR: 8284992: Fix misleading Vector API doc for LSHR operator [v2]

[Paul Sandoz]

On Thu, 21 Apr 2022 04:23:22 GMT, Jie Fu <jiefu at openjdk.org> wrote:

>> Hi all,
>> 
>> The Current Vector API doc for `LSHR` is
>> 
>> Produce a>>>(n&(ESIZE*8-1)). Integral only.
>> 
>> 
>> This is misleading which may lead to bugs for Java developers.
>> This is because for negative byte/short elements, the results computed by `LSHR` will be different from that of `>>>`.
>> For more details, please see https://github.com/openjdk/jdk/pull/8276#issue-1206391831 .
>> 
>> After the patch, the doc for `LSHR` is
>> 
>> Produce zero-extended right shift of a by (n&(ESIZE*8-1)) bits. Integral only.
>> 
>> 
>> Thanks.
>> Best regards,
>> Jie
>
> Jie Fu has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains three additional commits since the last revision:
> 
>  - Address review comments
>  - Merge branch 'master' into JDK-8284992
>  - 8284992: Fix misleading Vector API doc for LSHR operator

After talking with John here's what we think is a better approach than what I originally had in mind:
1. In the class doc of `VectorOperators` add a definition for `EMASK` occurring after the definition for `ESIZE`:

 * <li>{@code EMASK} — the bit mask of the operand type, where {@code EMASK=(1<<ESIZE*8)-1} 

2. Change `LSHR` to be:

/** Produce {@code (a&EMASK)>>>(n&(ESIZE*8-1))}.  Integral only. */

That more clearly gets across operating in the correct domain for sub-word operand types, which was the original intention (e.g. the right shift value).

-------------

PR: https://git.openjdk.java.net/jdk/pull/8291