RFR: 8284992: Fix misleading Vector API doc for LSHR operator

[Jie Fu]

On Wed, 20 Apr 2022 17:24:56 GMT, Paul Sandoz <psandoz 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
>
> We can raise attention to that:
> 
> /** Produce {@code a>>>(n&(ESIZE*8-1))} 
>   * (The operand and result are converted if the operand type is {@code byte} or {@code short}, see below).  Integral only.
>   * ...
>   */

Hi @PaulSandoz ,

I add a piece of notice at the end of the brief description of `LSHR` since not everyone would click and see the details without the change.
What do you think?
Thanks.

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

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