RFR(JAXP) 8182111: Package summary is missing in jdk.xml.dom module

[huizhe wang]

Hi Mandy,

Removed the change to module-info.java. While adding a description that 
the xpath package was from a working draft, I felt compelled to mention 
the latest specification. So essentially going back to your previous 
suggestion, explaining the difference between the working draft and the 
latest.

http://cr.openjdk.java.net/~joehw/jdk9/8182111/webrev02/

Thanks,
Joe

On 6/14/2017 9:57 PM, Mandy Chung wrote:
>> On Jun 14, 2017, at 9:29 PM, huizhe wang <huizhe.wang at oracle.com> wrote:
>>
>>
>> On 6/14/2017 4:58 PM, Mandy Chung wrote:
>>>> On Jun 14, 2017, at 4:19 PM, huizhe wang <huizhe.wang at oracle.com> wrote:
>>>>
>>>> Hi,
>>>>
>>>> Please review new package descriptions for jdk.xml.dom module. Note that the link to the XPath specificaiton in xpath/package-info.java is the formal release that is different from the one in the classes. The later was a working release now requires a login [1]. The only difference in the formal release is that the error numbers in XPathException were changed from 1 and 2 to 51 and 52. We may consider updating to the formal release in JDK 10.
>>>>
>>> The org/w3c/dom/xpath/* classes all have the link to [1].  The package summary  should explain the difference between two versions i.e. XPathException spec difference as it includes an accessible link.
>> The link may indeed be a source of confusion. Explaining details on the differences can also be troublesome because questions can be asked as why then we didn't update the package. So instead, I updated the module description to explain why these packages are here, and removed the links to avoid any potential confusion. In general, the only purpose of the module is to hold the APIs that old applications may have dependency on.
> Removing the link is a good alternative.  I suggest to mention it a working release and its date.
>
>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8182111
>>>> webrevs: http://cr.openjdk.java.net/~joehw/jdk9/8182111/webrev/
>>>>
>>> These APIs are supported @since 9.  They were not officially supported in the previous releases.
>> These were not SE APIs, and still are not SE APIs in 9. But they were indeed included in the JDK since 1.4, which is why we put them in this module that's for backward compatibility only. I therefore think it shall reflect the fact that they've been in the JDK @since 1.4. "@since 9" would give an impression that they are introduced in 9.
> This indeed has been a confusing story.  JDK-8042244 promotes these packages to be supported in JDK 9. I suggest @since 9 since 9 is the first release these APIs are promoted whereas previously are not supported.
>
>> Here's updated webrev:
>> http://cr.openjdk.java.net/~joehw/jdk9/8182111/webrev01/
> The change in module-info.java seems unnecessary and in fact it’s not for backward compatibility.  They are exported APIs and they are not endorsed by JAXP (hence not in java.xml).  I think the original module-info.java is adequate.
>
> Mandy