RFR [15] 8241014: Miscellaneous typos in documentation comments
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.
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<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.
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
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@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@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
--- 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 <ivan.gerasimov@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
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/XXXXXXX-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 <ivan.gerasimov@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
-- With kind regards, Ivan Gerasimov
Thanks Ivan, I merged your changes with mine and pushed the resulting changeset.
On 20 Mar 2020, at 20:11, Ivan Gerasimov <ivan.gerasimov@oracle.com> 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/XXXXXXX-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 <ivan.gerasimov@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
-- With kind regards, Ivan Gerasimov
On Mar 13, 2020, at 11:42 PM, Pavel Rappo <pavel.rappo@oracle.com> 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.
This is indeed a typo. Other changes (including Ivan's) also look fine to me. Thanks, Max
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.
+1 Paul.
On Mar 13, 2020, at 8:42 AM, Pavel Rappo <pavel.rappo@oracle.com> 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.
participants (5)
-
Ivan Gerasimov
-
Paul Sandoz
-
Pavel Rappo
-
Roger Riggs
-
Weijun Wang