RFR [15] 8245111: Update doc comments for improved processing by the Standard Doclet
Hello, Please review this trivial change for https://bugs.openjdk.java.net/browse/JDK-8245111: http://cr.openjdk.java.net/~prappo/8245111/webrev.00/ In addition to fixing the main issue, this includes a blanket change from "followed with" to "followed by" as the latter seemed idiomatic to me. -Pavel
Hi Pavel, This looks good to me - but English is not my native language ;-) cheers, -- daniel On 15/05/2020 13:35, Pavel Rappo wrote:
Hello,
Please review this trivial change for https://bugs.openjdk.java.net/browse/JDK-8245111:
http://cr.openjdk.java.net/~prappo/8245111/webrev.00/
In addition to fixing the main issue, this includes a blanket change from "followed with" to "followed by" as the latter seemed idiomatic to me.
-Pavel
+1 Cheers, Joe On 5/15/2020 7:00 AM, Daniel Fuchs wrote:
Hi Pavel,
This looks good to me - but English is not my native language ;-)
cheers,
-- daniel
On 15/05/2020 13:35, Pavel Rappo wrote:
Hello,
Please review this trivial change for https://bugs.openjdk.java.net/browse/JDK-8245111:
http://cr.openjdk.java.net/~prappo/8245111/webrev.00/
In addition to fixing the main issue, this includes a blanket change from "followed with" to "followed by" as the latter seemed idiomatic to me.
-Pavel
Hi Pavel, No problem with the "with" -> "by" changes. javax/naming/NameNotFoundException.java: 55 "initialized" -> "are initialized" java/util/jar/Attributes.java:594 The period was in the correct place. The second sentence is a separate comment about the use (non-use). "used for the extension mechanism that is no longer supported." Would read better as: "This name is obsolete, the extension mechanism is no longer supported." $.02, Roger On 5/15/20 10:00 AM, Daniel Fuchs wrote:
Hi Pavel,
This looks good to me - but English is not my native language ;-)
cheers,
-- daniel
On 15/05/2020 13:35, Pavel Rappo wrote:
Hello,
Please review this trivial change for https://bugs.openjdk.java.net/browse/JDK-8245111:
http://cr.openjdk.java.net/~prappo/8245111/webrev.00/
In addition to fixing the main issue, this includes a blanket change from "followed with" to "followed by" as the latter seemed idiomatic to me.
-Pavel
On 15 May 2020, at 16:53, Roger Riggs <Roger.Riggs@oracle.com> wrote:
Hi Pavel,
No problem with the "with" -> "by" changes.
javax/naming/NameNotFoundException.java: 55 "initialized" -> "are initialized"
java/util/jar/Attributes.java:594 The period was in the correct place. The second sentence is a separate comment about the use (non-use).
I considered that initially, but then saw how it was used on the adjacent field: /** * {@code Name} object for {@code Extension-List} manifest attribute * used for the extension mechanism that is no longer supported. */ public static final Name EXTENSION_LIST; Would you suggest making a similar fix here?
"used for the extension mechanism that is no longer supported."
Would read better as: "This name is obsolete, the extension mechanism is no longer supported."
$.02, Roger
On 5/15/20 10:00 AM, Daniel Fuchs wrote:
Hi Pavel,
This looks good to me - but English is not my native language ;-)
cheers,
-- daniel
On 15/05/2020 13:35, Pavel Rappo wrote:
Hello,
Please review this trivial change for https://bugs.openjdk.java.net/browse/JDK-8245111:
http://cr.openjdk.java.net/~prappo/8245111/webrev.00/
In addition to fixing the main issue, this includes a blanket change from "followed with" to "followed by" as the latter seemed idiomatic to me.
-Pavel
Hi Pavel, Yes, I think that would be an improvement. But its a slippery slope beyond what you originally observed and wanted to fix. Thanks, Roger On 5/15/20 11:59 AM, Pavel Rappo wrote:
On 15 May 2020, at 16:53, Roger Riggs <Roger.Riggs@oracle.com> wrote:
Hi Pavel,
No problem with the "with" -> "by" changes.
javax/naming/NameNotFoundException.java: 55 "initialized" -> "are initialized"
java/util/jar/Attributes.java:594 The period was in the correct place. The second sentence is a separate comment about the use (non-use). I considered that initially, but then saw how it was used on the adjacent field:
/** * {@code Name} object for {@code Extension-List} manifest attribute * used for the extension mechanism that is no longer supported. */ public static final Name EXTENSION_LIST;
Would you suggest making a similar fix here?
"used for the extension mechanism that is no longer supported."
Would read better as: "This name is obsolete, the extension mechanism is no longer supported."
$.02, Roger
On 5/15/20 10:00 AM, Daniel Fuchs wrote:
Hi Pavel,
This looks good to me - but English is not my native language ;-)
cheers,
-- daniel
On 15/05/2020 13:35, Pavel Rappo wrote:
Hello,
Please review this trivial change for https://bugs.openjdk.java.net/browse/JDK-8245111:
http://cr.openjdk.java.net/~prappo/8245111/webrev.00/
In addition to fixing the main issue, this includes a blanket change from "followed with" to "followed by" as the latter seemed idiomatic to me.
-Pavel
Roger, I think I will not do that even though it might be an improvement. If you look closely, the "attribute used for" pattern carpet-bombs that file. I guess if we are making this change you suggest, this should be done in a separate changeset. You are absolutely right saying that it's a slippery slope. So, unless you have arguments that outweigh the argument of consistency, I'd shelve your suggestion until better time. Thanks for your review! -Pavel
On 15 May 2020, at 17:34, Roger Riggs <Roger.Riggs@oracle.com> wrote:
Hi Pavel,
Yes, I think that would be an improvement. But its a slippery slope beyond what you originally observed and wanted to fix.
Thanks, Roger
On 5/15/20 11:59 AM, Pavel Rappo wrote:
On 15 May 2020, at 16:53, Roger Riggs <Roger.Riggs@oracle.com> wrote:
Hi Pavel,
No problem with the "with" -> "by" changes.
javax/naming/NameNotFoundException.java: 55 "initialized" -> "are initialized"
java/util/jar/Attributes.java:594 The period was in the correct place. The second sentence is a separate comment about the use (non-use). I considered that initially, but then saw how it was used on the adjacent field:
/** * {@code Name} object for {@code Extension-List} manifest attribute * used for the extension mechanism that is no longer supported. */ public static final Name EXTENSION_LIST;
Would you suggest making a similar fix here?
"used for the extension mechanism that is no longer supported."
Would read better as: "This name is obsolete, the extension mechanism is no longer supported."
$.02, Roger
On 5/15/20 10:00 AM, Daniel Fuchs wrote:
Hi Pavel,
This looks good to me - but English is not my native language ;-)
cheers,
-- daniel
On 15/05/2020 13:35, Pavel Rappo wrote:
Hello,
Please review this trivial change for https://bugs.openjdk.java.net/browse/JDK-8245111:
http://cr.openjdk.java.net/~prappo/8245111/webrev.00/
In addition to fixing the main issue, this includes a blanket change from "followed with" to "followed by" as the latter seemed idiomatic to me.
-Pavel
Hi Pavel, +1 No problem, local consistency is more important. Roger On 5/15/20 12:47 PM, Pavel Rappo wrote:
Roger, I think I will not do that even though it might be an improvement.
If you look closely, the "attribute used for" pattern carpet-bombs that file. I guess if we are making this change you suggest, this should be done in a separate changeset. You are absolutely right saying that it's a slippery slope. So, unless you have arguments that outweigh the argument of consistency, I'd shelve your suggestion until better time.
Thanks for your review!
-Pavel
On 15 May 2020, at 17:34, Roger Riggs <Roger.Riggs@oracle.com> wrote:
Hi Pavel,
Yes, I think that would be an improvement. But its a slippery slope beyond what you originally observed and wanted to fix.
Thanks, Roger
On 5/15/20 11:59 AM, Pavel Rappo wrote:
On 15 May 2020, at 16:53, Roger Riggs <Roger.Riggs@oracle.com> wrote:
Hi Pavel,
No problem with the "with" -> "by" changes.
javax/naming/NameNotFoundException.java: 55 "initialized" -> "are initialized"
java/util/jar/Attributes.java:594 The period was in the correct place. The second sentence is a separate comment about the use (non-use). I considered that initially, but then saw how it was used on the adjacent field:
/** * {@code Name} object for {@code Extension-List} manifest attribute * used for the extension mechanism that is no longer supported. */ public static final Name EXTENSION_LIST;
Would you suggest making a similar fix here?
"used for the extension mechanism that is no longer supported."
Would read better as: "This name is obsolete, the extension mechanism is no longer supported."
$.02, Roger
On 5/15/20 10:00 AM, Daniel Fuchs wrote:
Hi Pavel,
This looks good to me - but English is not my native language ;-)
cheers,
-- daniel
On 15/05/2020 13:35, Pavel Rappo wrote:
Hello,
Please review this trivial change for https://bugs.openjdk.java.net/browse/JDK-8245111:
http://cr.openjdk.java.net/~prappo/8245111/webrev.00/
In addition to fixing the main issue, this includes a blanket change from "followed with" to "followed by" as the latter seemed idiomatic to me.
-Pavel
Hi Pavel
On May 15, 2020, at 12:34 PM, Roger Riggs <Roger.Riggs@oracle.com> wrote:
Hi Pavel,
Yes, I think that would be an improvement. But its a slippery slope beyond what you originally observed and wanted to fix.
I understand why you want to fix this. When you look at the rest of the field descriptions, that will now show as the only field without a period in the description. Not sure what the best answer is. The rest is fine, this is the only puzzler :-) Best Lance
Thanks, Roger
On 5/15/20 11:59 AM, Pavel Rappo wrote:
On 15 May 2020, at 16:53, Roger Riggs <Roger.Riggs@oracle.com> wrote:
Hi Pavel,
No problem with the "with" -> "by" changes.
javax/naming/NameNotFoundException.java: 55 "initialized" -> "are initialized"
java/util/jar/Attributes.java:594 The period was in the correct place. The second sentence is a separate comment about the use (non-use). I considered that initially, but then saw how it was used on the adjacent field:
/** * {@code Name} object for {@code Extension-List} manifest attribute * used for the extension mechanism that is no longer supported. */ public static final Name EXTENSION_LIST;
Would you suggest making a similar fix here?
"used for the extension mechanism that is no longer supported."
Would read better as: "This name is obsolete, the extension mechanism is no longer supported."
$.02, Roger
On 5/15/20 10:00 AM, Daniel Fuchs wrote:
Hi Pavel,
This looks good to me - but English is not my native language ;-)
cheers,
-- daniel
On 15/05/2020 13:35, Pavel Rappo wrote:
Hello,
Please review this trivial change for https://bugs.openjdk.java.net/browse/JDK-8245111:
http://cr.openjdk.java.net/~prappo/8245111/webrev.00/
In addition to fixing the main issue, this includes a blanket change from "followed with" to "followed by" as the latter seemed idiomatic to me.
-Pavel
<http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037 Oracle Java Engineering 1 Network Drive Burlington, MA 01803 Lance.Andersen@oracle.com <mailto:Lance.Andersen@oracle.com>
participants (5)
-
Daniel Fuchs
-
Joe Wang
-
Lance Andersen
-
Pavel Rappo
-
Roger Riggs