RFR 8180349: Review JAXP Java SE 9 API javadocs

huizhe wang huizhe.wang at oracle.com
Tue May 23 23:27:21 UTC 2017



On 5/23/2017 3:05 PM, Lance Andersen wrote:
> Hi Joe,
>
> Looks good overall and one comment below on top of Roger’s:
>> On May 23, 2017, at 4:38 PM, Roger Riggs <Roger.Riggs at oracle.com> wrote:
>>
>> Hi  Joe,
>>
>> Looks good, a few minor editorial suggestions:
>>
>> javax/transform/sax/package-info.java:
>> - line 28:  I don't think the '-' belongs after SAX2 in the first sentence.
>>
>> javax/transform/dom/package-info.java:
>> line 28:  ditto it is more readable without the '-'.
>>
>> javax/stream/package-info.java:
>> line 33:  "easy pipelining".    -> "easy to pipeline" to
>> match the "to..., to..." structure of the sentence.
>>
>> line 43: "may be located" -> "is located"
>>
>> javax/validation/package-info.java:
>> line 68:  "is more preferable" -> "is preferred"
>>
>> javax/xml/catalog/package-info.java:
>> line 34:  "JDK XML Processors" -> "XML Processors”
> Is this trying to refer to the JAXP provided implementations?  if so, perhaps reword to try and make that clearer

Yes. It's probably not appropriate for the API docs to mention "JDK", so 
I've removed it as Roger commented. I think we are fine since we cover 
the topic in details with sample code in the developer guide.

Here's updated webrevs:
http://cr.openjdk.java.net/~joehw/jdk9/8180349/webrev01/

Thanks,
Joe

>
>> Thanks, Roger
>>
>>
>>
>>
>> On 5/23/2017 1:01 PM, huizhe wang wrote:
>>> Hi,
>>>
>>> Please review an update to the JAXP Java SE 9 API javadocs.
>>>
>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8180349
>>> webrevs: http://cr.openjdk.java.net/~joehw/jdk9/8180349/webrev/
>>>
>>> There's a lot of format changes while converting to package-info.java, but only minor (wording) changes to the original documentation. All in all, including the new package descriptions, there's no material change to the APIs or description of them. Below are some details.
>>>
>>> javax.xml
>>>     New package description.
>>>
>>> javax.xml.catalog
>>>     Added a summary of the package.
>>>
>>> javax.xml.datatype
>>>     Added "Defines" at the beginning. Added @since.
>>>
>>> javax.xml.namespace
>>>     Added @since.
>>>
>>> javax.xml.parsers
>>>     Rephrased, added a short description of the plugability layer.
>>>
>>> javax.xml.stream and javax.xml.stream.*
>>>     New package description.
>>>
>>> javax.xml.transform
>>>     Added javax.xml.transform.stax to the description.
>>>
>>> javax.xml.transform.dom
>>>     Format only.
>>>
>>> javax.xml.transform.sax
>>>     Removed from the 1st paragraph the summary that's redundant to the next few paragraphs, which made it consistent with the .dom package.   The last paragraph described an example that never existed. Rephrased the paragraph without mentioning an example.
>>>
>>> javax.xml.transform.stax
>>>     New
>>>
>>> javax.xml.transform.stream
>>>     The 1st statement is made consistent to that of .dom/sax/stax above
>>>
>>> javax.xml.validation
>>>     Format and minor wording changes. Under Support for additional schema langauges, I removed the words "as of JDK 1.5...".
>>>
>>> javax.xml.xpath
>>>     Format and minor wording changes.
>>>
>>> org.w3c.dom
>>>     Format only
>>>
>>> org.w3c.dom.bootstrap .events .ls .traversal .views
>>>     New package descriptions.
>>>
>>> org.w3c.dom.range
>>>     Removed the paragraphs copied from the DOM specification that states DOM is language-neutral and etc. since they have nothing to do with the Java package.
>>>
>>> org.xml.sax
>>>     minor wording changes. The starting sentence changed to start with "provides" to be consistent with the other packages. The last sentence "XMLReader implementations need not support them" is changed to "XMLReader implementations are not required to support them".
>>>
>>> org.xml.sax.ext, .helpers
>>>     Only the start, e.g. "Provides..."
>>>
>>> Thanks,
>>> Joe
>>>
>   <http://oracle.com/us/design/oracle-email-sig-198324.gif>
>   <http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
>   <http://oracle.com/us/design/oracle-email-sig-198324.gif>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 <mailto:Lance.Andersen at oracle.com>
>
>
>



More information about the core-libs-dev mailing list