RFR: JDK-8185464: Link issues in java.xml module

[Lance Andersen]

> On Jul 27, 2017, at 5:10 PM, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Lance,
> 
> It is intentional that the Author designation has disappeared from the javax.xml.datatype package summary. 

I was just about to send another email, as I realized that we were not using -author after I hit send.

Thanks for the follow up :-)

Best
Lance
> The following lines
> 
>  154  * <ul>
>  155  *     <li>Author <a href="mailto:Jeff.Suttor at Sun.com" <mailto:Jeff.Suttor at Sun.com>>Jeff Suttor</a></li>
> were normalized to
>  152  * @author <a href="mailto:Jeff.Suttor at Sun.com" <mailto:Jeff.Suttor at Sun.com>>Jeff Suttor</a>
> and since we do not use the -author option when generating the main API doc bundle, the author information is not produced in the output. This is the same for all other uses of @author in our source code doc comments.  Here is the relevant extract from the command-line help:
> 
> Provided by the Standard doclet:
>     -author       Include @author paragraphs
> 
> 
> You can see the differences in the generated output for JDK 9:
> http://download.java.net/java/jdk9/docs/api/javax/xml/datatype/package-summary.html <http://download.java.net/java/jdk9/docs/api/javax/xml/datatype/package-summary.html>
> 
> 
> Author Jeff Suttor <mailto:Jeff.Suttor at Sun.com>
> See W3C XML Schema 1.0 Part 2, Section 3.2.7-14 <http://www.w3.org/TR/xmlschema-2/#dateTime>
> See XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration <http://www.w3.org/TR/xpath-datamodel#dt-dayTimeDuration>
> See XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration <http://www.w3.org/TR/xpath-datamodel#dt-yearMonthDuration>
> Since 1.5
> Since:
> 1.5
> 
> (note the non-standard Author and See entries, and the double "Since" info)
> 
> and proposed, after the patch,
> http://cr.openjdk.java.net/~jjg/8185464/api.00/javax/xml/datatype/package-summary.html <http://cr.openjdk.java.net/~jjg/8185464/api.00/javax/xml/datatype/package-summary.html>
> 
> Since:
> 1.5
> See Also:
> W3C XML Schema 1.0 Part 2, Section 3.2.7-14 <http://www.w3.org/TR/xmlschema-2/#dateTime>, XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration <http://www.w3.org/TR/xpath-datamodel#dt-dayTimeDuration>, XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration <http://www.w3.org/TR/xpath-datamodel#dt-yearMonthDuration>
> -- Jon
> 
> 
> 
> On 07/27/2017 01:49 PM, Lance Andersen wrote:
>> Hi Jon,
>> 
>> Overall it looks good.  Maybe it is my browser, but I do not see the Author tag in the DataType package summary though it is there in JDK 8 and looks like it should still display unless I am missing something…
>> 
>> Best
>> Lance
>>> On Jul 27, 2017, at 4:35 PM, Jonathan Gibbons <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> wrote:
>>> 
>>> Continuing the documentation cleanup:
>>> 
>>> Please review the following simple changes to the API documentation for the java.xml module,
>>> to address issues with links in these files.
>>> 
>>> Some missing ids have been declared as appropriate.
>>> 
>>> The issue with a mailto: link in the public API to an obsolete address has been side-stepped
>>> by converting a number of explicit Author and See constructs to the equivalent @author and @see
>>> tags. Since we don't publish authors in the generated documentation, that addresses the
>>> appearance of the bad mailto: link.  I'll leave it to someone else to take on the general task of
>>> cleaning up the many references to obsolete @sun.com <http://sun.com/> email addresses in the source code.
>>> 
>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8185464 <https://bugs.openjdk.java.net/browse/JDK-8185464>
>>> Webrev: http://cr.openjdk.java.net/~jjg/8185464/webrev.00/ <http://cr.openjdk.java.net/%7Ejjg/8185464/webrev.00/>
>>> API: http://cr.openjdk.java.net/~jjg/8185464/api.00/overview-summary.html <http://cr.openjdk.java.net/%7Ejjg/8185464/api.00/overview-summary.html>
>>> 
>>> -- Jon
>>> 
>>> 
>> 
>> <Mail Attachment.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>
>>  <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>
>> 
>> 
>> 
> 

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