RFR [16/java.xml] 8251561: Fix doclint warnings in the java.xml package

[Roger Riggs]

Hi Erik,

org.w3c is in third party code that is not being updated. There is a 
balance between
ignoring the warnings and doing a bunch of editing that would 
overwritten by a future update.

$.02, Roger


On 8/25/20 2:58 PM, Erik Joelsson wrote:
> Build change looks ok, but why is it needed? You are fixing a bunch of 
> warnings in one part of the source and disabling them in another part. 
> Is there some other change incoming that will enable more warning 
> categories by default?
>
> /Erik
>
> On 2020-08-25 11:47, Joe Wang wrote:
>> Cc-ing build-dev at openjdk.java.net (makefile change: make/Docs.gmk)
>> Updated webrev: 
>> http://cr.openjdk.java.net/~joehw/jdk16/8251561/webrev_04/
>>
>> Thanks Roger! Please see inline comments.
>>
>> On 8/25/20 8:09 AM, Roger Riggs wrote:
>>> Hi Joe,
>>>
>>> Eliminating the checking for warnings in org.w3c is fine. Please be 
>>> more specific in the comment.
>>>
>>> "Ignore the doclint warnings in the W3C DOM package"
>>
>> Updated.
>>> org/xml/...: If we're suppressing the warnings for org/xml/... then 
>>> the files changes are unnecessary?
>>
>> Did you mean org/w3c? We're only suppressing the warnings for org/w3c 
>> where the DOM package is in, but not org/xml where SAX is in.
>>
>>>
>>> Remove the addition of -Xmaxwarns, it should stay the default.
>>
>> Done.
>>>
>>> Since its a makefile change, please copy build-dev at openjdk.java.net.
>>
>> Cc-ed
>>>
>>> The first line comments should terminate with a period ".".
>>>
>>> javax/xml/stream/FactoryConfigurationError.java:40
>>> javax/xml/stream/XMLStreamException.java:41
>>> javax/xml/xpath/XPathException.java:44  And capitable "Serializable".
>>>
>>>
>>> javax/xml/stream/events/Attribute.java: 50; add "normalized" to the 
>>> @return line so it is the same as the first line.
>>> For simple get methods, the @return mimics the first line.
>>>
>>> javax/xml/stream/events/NotationDeclaration.java:43  add "notation"
>>
>> Updated webrev including all of the above:
>>
>> http://cr.openjdk.java.net/~joehw/jdk16/8251561/webrev_04/
>>
>>>
>>>
>>>
>>> Thanks, Roger
>>>
>>> p.s.  There is lots of other cleanup of the javadoc, using @code 
>>> around true, false,
>>> missing periods at the end of first sentences, etc.  But that's a 
>>> different task.
>>
>> Created a bug to keep track of this:
>> https://bugs.openjdk.java.net/browse/JDK-8252328
>>
>> Thanks,
>> Joe
>>>
>>>
>>>
>>> On 8/24/20 5:44 PM, Joe Wang wrote:
>>>> Hi all,  adding Roger's comment for the make file to webrev_02 (the 
>>>> only change to webrev_01 is Docs.gmk):
>>>>
>>>> http://cr.openjdk.java.net/~joehw/jdk16/8251561/webrev_02/
>>>>
>>>> Thanks,
>>>> Joe
>>>>
>>>> On 8/21/20 12:49 PM, naoto.sato at oracle.com wrote:
>>>>> +1
>>>>>
>>>>> Naoto
>>>>>
>>>>> On 8/21/20 12:24 PM, Lance Andersen wrote:
>>>>>> Hi Joe,
>>>>>>
>>>>>> This looks OK.
>>>>>>
>>>>>>
>>>>>>
>>>>>>> On Aug 21, 2020, at 2:23 PM, Joe Wang <huizhe.wang at oracle.com> 
>>>>>>> wrote:
>>>>>>>
>>>>>>> Pelase review a patch to add the missing @return, @throws, 
>>>>>>> @param statements in the java.xml package (excluding the DOM 
>>>>>>> component).
>>>>>>>
>>>>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8251561
>>>>>>> CSR: https://bugs.openjdk.java.net/browse/JDK-8251995
>>>>>>>
>>>>>>> webrev: http://cr.openjdk.java.net/~joehw/jdk16/8251561/webrev_01/
>>>>>>>
>>>>>>> Thanks,
>>>>>>> Joe
>>>>>>
>>>>>>
>>>>>> Best
>>>>>> Lance
>>>>>> ------------------
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>> 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
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>
>>>
>>