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

Jonathan Gibbons jonathan.gibbons at oracle.com
Thu Jul 27 21:10:18 UTC 2017


Lance,

It is intentional that the Author designation has disappeared from the 
javax.xml.datatype package summary.  The following lines

  154  * <ul>
  155  *     <li>Author <a href="mailto:Jeff.Suttor at Sun.com">Jeff Suttor</a></li>

were normalized to

  152  * @author <a href="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


    ------------------------------------------------------------------------

      * 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

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