RFR [15] 8245111: Update doc comments for improved processing by the Standard Doclet

[Pavel Rappo]

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 at 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 at 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
>>>>> 
>