RFR; [docs,15] JDK-8248060 small HTML issues in java.xml package-info.java files

[Joe Wang]

Looks good to me.

The upstream SAX hasn't evolved for a long time (and there's no plan to 
do so). I think we're okay to make small changes. For the 2nd case, I 
think it's good enough since there are links to the classes at the 
beginning of the sentence -- a minor inconvenience (vs a straight link 
to the method). Alternatively, we could choose the more frequently used 
InputFactory, e.g. {@linkplain XMLInputFactory#newFactory newFactory}.

Cheers,
Joe

On 6/22/2020 3:55 PM, Jonathan Gibbons wrote:
> Please review a couple of trivial fixes for a couple of issues in 
> java.xml, reported by doclint.
>
> I realize we typically don't touch upstream code, but I'm hoping this 
> is small enough to
> be reasonable.
>
> In the first case, there is an unnecessary `<p>` before a `<table>`.
>
> In the second case, there's a bad `{@link newFactory}`. Not only is 
> the syntax bad,
> but the method is defined in multiple classes in the same package, and 
> overloaded as
> well: i.e. there is no easy/reasonable target for the link. The 
> simple/localized fix is
> just to change `{@link}` to `{@code}`.  A better solution (for someone 
> else to do)
> would be to rewrite the sentence altogether.
>
> -- Jon
>
> JBS: https://bugs.openjdk.java.net/browse/JDK-8248060
>
> Patch:
>
>  hg diff -R open open/src/java.xml
> diff -r 9cfa0137612f 
> src/java.xml/share/classes/javax/xml/stream/package-info.java
> --- a/src/java.xml/share/classes/javax/xml/stream/package-info.java 
> Mon Jun 22 13:37:41 2020 -0700
> +++ b/src/java.xml/share/classes/javax/xml/stream/package-info.java 
> Mon Jun 22 15:44:55 2020 -0700
> @@ -41,8 +41,8 @@
>   * <p>
>   * StAX supports plugability with {@link XMLInputFactory} and
>   * {@link XMLOutputFactory} that define how an implementation is
> - * located through a process as described in the {@link newFactory}
> - * method.
> + * located through a process as described in the {@code newFactory}
> + * methods.
>   *
>   *
>   * @since 1.6
> diff -r 9cfa0137612f 
> src/java.xml/share/classes/org/xml/sax/package-info.java
> --- a/src/java.xml/share/classes/org/xml/sax/package-info.java Mon Jun 
> 22 13:37:41 2020 -0700
> +++ b/src/java.xml/share/classes/org/xml/sax/package-info.java Mon Jun 
> 22 15:44:55 2020 -0700
> @@ -27,7 +27,6 @@
>   * Provides the interfaces for the Simple API for XML (SAX). Supports 
> both
>   * the SAX1 and SAX2 APIs.
>   *
> - * <p>
>   * <h2> SAX2 Standard Feature Flags </h2>
>   *
>   * <p>
>