Re: RFR [15] 8241014: Miscellaneous typos in documentation comments
Thanks Ivan, I merged your changes with mine and pushed the resulting changeset.
> On 20 Mar 2020, at 20:11, Ivan Gerasimov wrote:
>
> Thank you Paul!
>
> grep found a few more occurrences of 'equals to' across java.base, so I
> fixed them as well.
>
> Here's the updated webrev:
>
> http://cr.openjdk.java.net/~igerasim/XXX-typos/01/webrev/
>
>
> Pavel, I checked your portion of correction, everything looks good to me!
>
> One minor nit: In src/java.base/share/classes/java/util/StringJoiner.java
> can you please wrap the modified line, so it won't be that long?
>
>
> With kind regards,
>
> Ivan
>
>
> On 3/20/20 10:16 AM, Paul Sandoz wrote:
>> --- a/src/java.base/share/classes/java/lang/invoke/MethodType.java
>> +++ b/src/java.base/share/classes/java/lang/invoke/MethodType.java
>> @@ -1379,12 +1379,12 @@
>>/**
>> * This implementation returns {@code true} if {@code obj} is
>> another
>> - * {@code WeakEntry} whose referent is equals to this referent,
>> or
>> - * if {@code obj} is equals to the referent of this. This allows
>> + * {@code WeakEntry} whose referent equals to this referent, or
>> + * if {@code obj} equals to the referent of this. This allows
>> * lookups to be made without wrapping in a {@code WeakEntry}.
>> *
>> * @param obj the object to compare
>> - * @return true if {@code obj} is equals to this or the
>> referent of this
>> + * @return true if {@code obj} equals to this or the referent
>> of this
>> * @see MethodType#equals(Object)
>> * @see Object#equals(Object)
>> Use either:
>>
>> whose referent is equal to this referent,
>>
>> or
>>
>> whose referent equals this referent,
>>
>> The former is easier just delete the ’s’.
>>
>> Other bits look good.
>>
>> Paul.
>>
>>> On Mar 13, 2020, at 7:03 PM, Ivan Gerasimov
>>> wrote:
>>>
>>> Hi Pavel!
>>>
>>> Can this please be combined with my collection of typos?
>>>
>>> http://cr.openjdk.java.net/~igerasim/XXX-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 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
>>>
> --
> With kind regards,
> Ivan Gerasimov
>
Re: RFR [15] 8241014: Miscellaneous typos in documentation comments
Thank you Paul!
grep found a few more occurrences of 'equals to' across java.base, so
I fixed them as well.
Here's the updated webrev:
http://cr.openjdk.java.net/~igerasim/XXX-typos/01/webrev/
Pavel, I checked your portion of correction, everything looks good to me!
One minor nit: In
src/java.base/share/classes/java/util/StringJoiner.java can you please
wrap the modified line, so it won't be that long?
With kind regards,
Ivan
On 3/20/20 10:16 AM, Paul Sandoz wrote:
--- a/src/java.base/share/classes/java/lang/invoke/MethodType.java
+++ b/src/java.base/share/classes/java/lang/invoke/MethodType.java
@@ -1379,12 +1379,12 @@
/**
* This implementation returns {@code true} if {@code obj} is
another
- * {@code WeakEntry} whose referent is equals to this referent, or
- * if {@code obj} is equals to the referent of this. This allows
+ * {@code WeakEntry} whose referent equals to this referent, or
+ * if {@code obj} equals to the referent of this. This allows
* lookups to be made without wrapping in a {@code WeakEntry}.
*
* @param obj the object to compare
- * @return true if {@code obj} is equals to this or the referent
of this
+ * @return true if {@code obj} equals to this or the referent of
this
* @see MethodType#equals(Object)
* @see Object#equals(Object)
Use either:
whose referent is equal to this referent,
or
whose referent equals this referent,
The former is easier just delete the ’s’.
Other bits look good.
Paul.
On Mar 13, 2020, at 7:03 PM, Ivan Gerasimov wrote:
Hi Pavel!
Can this please be combined with my collection of typos?
http://cr.openjdk.java.net/~igerasim/XXX-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 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
--
With kind regards,
Ivan Gerasimov
Re: RFR [15] 8241014: Miscellaneous typos in documentation comments
+1 Paul. > On Mar 13, 2020, at 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 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. >
Re: RFR [15] 8241014: Miscellaneous typos in documentation comments
--- a/src/java.base/share/classes/java/lang/invoke/MethodType.java
+++ b/src/java.base/share/classes/java/lang/invoke/MethodType.java
@@ -1379,12 +1379,12 @@
/**
* This implementation returns {@code true} if {@code obj} is
another
- * {@code WeakEntry} whose referent is equals to this referent, or
- * if {@code obj} is equals to the referent of this. This allows
+ * {@code WeakEntry} whose referent equals to this referent, or
+ * if {@code obj} equals to the referent of this. This allows
* lookups to be made without wrapping in a {@code WeakEntry}.
*
* @param obj the object to compare
- * @return true if {@code obj} is equals to this or the referent
of this
+ * @return true if {@code obj} equals to this or the referent of
this
* @see MethodType#equals(Object)
* @see Object#equals(Object)
Use either:
whose referent is equal to this referent,
or
whose referent equals this referent,
The former is easier just delete the ’s’.
Other bits look good.
Paul.
> On Mar 13, 2020, at 7:03 PM, Ivan Gerasimov wrote:
>
> Hi Pavel!
>
> Can this please be combined with my collection of typos?
>
> http://cr.openjdk.java.net/~igerasim/XXX-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 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
>
Re: RFR [15] 8241014: Miscellaneous typos in documentation comments
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: patr...@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 wrote: > > Hi Pavel! > > Can this please be combined with my collection of typos? > > http://cr.openjdk.java.net/~igerasim/XXX-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 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 >
Re: RFR [15] 8241014: Miscellaneous typos in documentation comments
Looks fine. On 3/13/20 11: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 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.
