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

[Roger Riggs]

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