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

[Lance Andersen]

Hi Pavel

> On May 15, 2020, at 12:34 PM, 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.

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

 <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 at oracle.com <mailto:Lance.Andersen at oracle.com>