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

[Erik Joelsson]

On 2020-08-25 12:21, Roger Riggs wrote:
> 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.
>
Yes, I get that part, but why are those warnings not triggered today? I 
don't see any change enabling more warnings from the build.

/Erik

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