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

[Joe Wang]

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