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

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Jonathan Gibbons
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 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/
API: http://cr.openjdk.java.net/~jjg/8185464/api.00/overview-summary.html

-- Jon


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Lance Andersen
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 <[hidden email]> 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 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/
> API: http://cr.openjdk.java.net/~jjg/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
[hidden email] <mailto:[hidden email]>



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Jonathan Gibbons
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:[hidden email]">Jeff Suttor</a></li>

were normalized to

  152  * @author <a href="mailto:[hidden email]">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:[hidden email]>
      * 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
>> <[hidden email] <mailto:[hidden email]>> 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
> [hidden email] <mailto:[hidden email]>
>
>
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Lance Andersen

> On Jul 27, 2017, at 5:10 PM, Jonathan Gibbons <[hidden email]> 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:[hidden email]" <mailto:[hidden email]>>Jeff Suttor</a></li>
> were normalized to
>  152  * @author <a href="mailto:[hidden email]" <mailto:[hidden email]>>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:[hidden email]>
> 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 <[hidden email] <mailto:[hidden email]>> 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
>> [hidden email] <mailto:[hidden email]>
>>
>>
>>
>

 <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
[hidden email] <mailto:[hidden email]>



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

huizhe wang
Looks good to me too.

A side issue, the 'fixedNav' block is preventing the browser from
showing the exact content of an inner anchor, the Nav section covers
that much of content as its height. If I click on the link to
CatalogFeatures.html#PREFER for example, I'd get to see DEFER.

Best,
Joe

On 7/27/2017 2:12 PM, Lance Andersen wrote:

>> On Jul 27, 2017, at 5:10 PM, Jonathan Gibbons <[hidden email]> 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:[hidden email]" <mailto:[hidden email]>>Jeff Suttor</a></li>
>> were normalized to
>>   152  * @author <a href="mailto:[hidden email]" <mailto:[hidden email]>>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:[hidden email]>
>> 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 <[hidden email] <mailto:[hidden email]>> 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
>>> [hidden email] <mailto:[hidden email]>
>>>
>>>
>>>
>   <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
> [hidden email] <mailto:[hidden email]>
>
>
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Jonathan Gibbons


On 07/27/2017 04:58 PM, huizhe wang wrote:
> Looks good to me too.
>
> A side issue, the 'fixedNav' block is preventing the browser from
> showing the exact content of an inner anchor, the Nav section covers
> that much of content as its height. If I click on the link to
> CatalogFeatures.html#PREFER for example, I'd get to see DEFER.
>
> Best,
> Joe

I noticed the fixedNav issue when checking this out yesterday, and I
already filed

8185368: Navbar causes confusing behavior when navigating to a link
https://bugs.openjdk.java.net/browse/JDK-8185368

-- Jon
Loading...