RFR 8180349: Review JAXP Java SE 9 API javadocs

[Roger Riggs]

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"

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
>