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

[Jie Fu]

On Wed, 20 Apr 2022 00:46:32 GMT, Paul Sandoz <psan...@openjdk.org> wrote:

> The intended pattern for the operator tokens is to present a short symbolic 
> description using Java operators and common methods. It would be good to try 
> and keep with this pattern, and clarify for the extra cases. Here's what i 
> had in mind:
> 
> ```
> /** Produce {@code a>>>(n&(ESIZE*8-1))}.  Integral only. 
>   * <p>
>   * For operand types {@code byte} and {@code short} the operation behaves as 
> if the operand is first implicitly widened  
>   * to an {@code int} value with {@code (a & ((1 << ESIZE) - 1))} the result 
> of which is then applied as the operand to this 
>   * operation, the result of the operation is then narrowed from {@code int} 
> to the operand type using an explicit cast.
>   */
> public static final /*bitwise*/ Binary LSHR;
> ```

This works only if people would like to read the detailed description of `LSHR` 
carefully.

Actually, most developers would still see the brief description first.
<img width="1087" alt="image" 
src="https://user-images.githubusercontent.com/19923746/164127620-90a73d29-868e-46d8-9562-2c5b2021f13b.png";>
 
If they don't click out the detailed description further or don't read it 
carefully, it's still misleading.

Maybe, we'd better not to use `>>>` in the brief description since `LSHR` 
behaves differently with the common used `>>>`.
What do you think?

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

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