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

[Erik Joelsson]

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