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

[Erik Joelsson]

Ah, I was looking for that kind of information in the bug report, but 
couldn't find any.

/Erik

On 2020-08-25 13:20, Joe Wang wrote:
> 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
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>
>