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

[Joe Wang]

Hi Erik,

We're acting on a report Jon generated separately. The warnings checks 
are currently disabled (see line 106 JAVADOC_DISABLED_DOCLINT := 
accessibility html missing syntax reference).

-Joe

On 8/25/20 12:39 PM, Erik Joelsson wrote:
>
> 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
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>
>>>>>
>>>>
>>