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