RFR [15] 8241014: Miscellaneous typos in documentation comments

[Pavel Rappo]

Hi Ivan,

Your changes look good to me. Thanks for doing this.
I will merge your changes into that patch of mine.

1. One thing that your change highlighted is that use of FQN here:

    public int read(java.nio.CharBuffer target) throws IOException

It's been there for ages, but I believe can now safely go away after

    $ hg log -v -r 49262
    changeset:   49262:1b3ee04e3e54
    user:        rriggs
    date:        Mon Mar 19 09:58:41 2018 -0400
    files:       src/java.base/share/classes/java/io/Reader.java src/java.base/share/classes/java/io/Writer.java test/jdk/java/io/Reader/NullReader.java test/jdk/java/io/Writer/NullWriter.java
    description:
    8196298: Add null Reader and Writer
    Reviewed-by: bpb, forax, smarks, alanb, rriggs
    Contributed-by: patrick at reini.net

as this latter change brought

    import java.nio.CharBuffer;

Unless people want to keep that FQN for some other reasons. For example, to
emphasize that CharBuffer does not belong to java.io, or so it does not get
confused with unrelated concepts like BufferedReader.defaultCharBufferSize, etc.

2. Typos aside, this MethodType.ConcurrentWeakInternSet.WeakEntry#equals
has peculiar semantics!

Paul Sandoz might be a good fit for reviewing changes in both java.util.stream
(mine) and java.util.Arrays (yours).

-Pavel

> On 14 Mar 2020, at 02:03, Ivan Gerasimov <ivan.gerasimov at oracle.com> wrote:
> 
> Hi Pavel!
> 
> Can this please be combined with my collection of typos?
> 
> http://cr.openjdk.java.net/~igerasim/XXXXXXX-typos/00/webrev/
> 
> Just to save cycles on reviewing :)
> 
> With kind regards,
> 
> Ivan
> 
> 
> On 3/13/20 8:42 AM, Pavel Rappo wrote:
>> Hello,
>> 
>> Please review the change for https://bugs.openjdk.java.net/browse/JDK-8241014:
>> 
>>   http://cr.openjdk.java.net/~prappo/8241014/webrev.00/
>> 
>> This is a documentation cleanup. There are no code changes involved,
>> and the changes in documentation are mostly trivial.
>> 
>> The following packages are affected:
>> 
>>     java.lang,
>>     java.nio.file,
>>     java.nio.file.attribute,
>>     java.security,
>>     java.time.chrono,
>>     java.time.temporal,
>>     java.util,
>>     java.util.regex,
>>     java.util.stream,
>>     javax.crypto,
>>     javax.security.cert,
>>     javax.tools
>> 
>> That said, there are two changes that I'd prefer to be carefully reviewed by
>> the experts in the corresponding areas.
>> 
>> The first one is for a suspected typo in the javax.crypto.CryptoPolicyParser
>> class, "AlgrithomParameterSpec". It is not unheard-of for typos to be kept and
>> supported for the sake of backward compatibility. Sadly, we have a number of
>> those in OpenJDK. Even though I performed reasonable checks, the proposed fix
>> should better be verified by the security folk.
>> 
>> The second one is for the doc comment for the java.util.stream.Stream.collect method.
>> 
>>      @apiNote
>>      The following will accumulate strings into an ArrayList:
>> 
>>          List<String> asList = stringStream.collect(Collectors.toList());
>> 
>> Given that the spec for Collectors.toList() clearly says that
>> 
>>     ...There are no guarantees on the type, mutability, serializability, or
>>     thread-safety of the List returned;...
>> 
>> I'd assume that @apiNote should be fixed as proposed.
>> 
>> -Pavel
>> 
>> P.S. Apologies for spamming multiple mailing lists.
>> 
> -- 
> With kind regards,
> Ivan Gerasimov
>