Quantcast

RFR 9: 8180082 : Broken javadoc links

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

RFR 9: 8180082 : Broken javadoc links

roger riggs
Please review corrections to broken javadoc links:
  - links to the serialization spec now in ./specs/serialization
  - links in java.lang to java/util/Spliterator
  - link in ModuleLayer to Classloader
  - Links using ../../../.. do not work well when they show up in some
indexes; they should use @docRoot

webrev:
   http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/

Issue:
   https://bugs.openjdk.java.net/browse/JDK-8180082

Thanks, Roger

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

Re: RFR 9: 8180082 : Broken javadoc links

Mandy Chung

> On May 10, 2017, at 11:22 AM, Roger Riggs <[hidden email]> wrote:
>
> Please review corrections to broken javadoc links:
> - links to the serialization spec now in ./specs/serialization
> - links in java.lang to java/util/Spliterator
> - link in ModuleLayer to Classloader
> - Links using ../../../.. do not work well when they show up in some indexes; they should use @docRoot
>
> webrev:
>  http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/

Looks good.

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

Re: RFR 9: 8180082 : Broken javadoc links

Brian Burkhalter-2
In reply to this post by roger riggs
Hi Roger,

Looks all right to me. I assume you will have already built the actual docs and clicked through the updated links. Always a bit painful …

Thanks,

Brian

On May 10, 2017, at 11:22 AM, Roger Riggs <[hidden email]> wrote:

> Please review corrections to broken javadoc links:
> - links to the serialization spec now in ./specs/serialization
> - links in java.lang to java/util/Spliterator
> - link in ModuleLayer to Classloader
> - Links using ../../../.. do not work well when they show up in some indexes; they should use @docRoot
>
> webrev:
>  http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/
>
> Issue:
>  https://bugs.openjdk.java.net/browse/JDK-8180082

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

Re: RFR 9: 8180082 : Broken javadoc links

Chris Hegarty

On May 10, 2017, at 11:22 AM, Roger Riggs <[hidden email]> wrote:

> Please review corrections to broken javadoc links:
> - links to the serialization spec now in ./specs/serialization
> - links in java.lang to java/util/Spliterator
> - link in ModuleLayer to Classloader
> - Links using ../../../.. do not work well when they show up in some indexes; they should use @docRoot
>
> webrev:
> http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/

Looks good Roger.

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

Re: RFR 9: 8180082 : Broken javadoc links

Daniel Fuchs
In reply to this post by roger riggs
Hi Roger,

I'm surprised to see we have <a href=""...> style links in .java
files to link to package summary and java APIs for classes and
methods, when {@link } should work...

For instance in this file:
http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/src/jdk.management/share/classes/com/sun/management/package-info.java.frames.html

Does:

   29  * <a
href="{@docRoot}/../../../../api/java/lang/management/package-summary.html">

actualy works?? Looks like it has too many ../.. to me...

I suspect (hope?) it could be advantageously replaced by {@link
java.lang.management}.


Similarly:

   36  * <a
href="{@docRoot}/java/lang/management/ManagementFactory.html#getPlatformMBeanServer()">
   37  * java.lang.management.ManagementFactory.getPlatformMBeanServer</a>

could probably be {@link
java.lang.management.ManagementFactory#getPlatformMBeanServer()}


This also reminds me that as part of the technical debt we might also
think about replacing package.html files by their more modern
package-info.java counterpart - but that's probably for another day...


cheers,

-- daniel



On 10/05/2017 19:22, Roger Riggs wrote:

> Please review corrections to broken javadoc links:
>  - links to the serialization spec now in ./specs/serialization
>  - links in java.lang to java/util/Spliterator
>  - link in ModuleLayer to Classloader
>  - Links using ../../../.. do not work well when they show up in some
> indexes; they should use @docRoot
>
> webrev:
>   http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/
>
> Issue:
>   https://bugs.openjdk.java.net/browse/JDK-8180082
>
> Thanks, Roger
>

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

Re: RFR 9: 8180082 : Broken javadoc links

roger riggs
Hi,

Thanks for the review and suggestions.
{@link ...} will work those links;  some hrefs will remain in cases
where the link is to an "id" of some
element that is not a method or field name.

Webrev updated in place:
     http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/

Thanks, Roger

On 5/11/2017 5:24 AM, Daniel Fuchs wrote:

> Hi Roger,
>
> I'm surprised to see we have <a href=""...> style links in .java
> files to link to package summary and java APIs for classes and
> methods, when {@link } should work...
>
> For instance in this file:
> http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/src/jdk.management/share/classes/com/sun/management/package-info.java.frames.html 
>
>
> Does:
>
>   29  * <a
> href="{@docRoot}/../../../../api/java/lang/management/package-summary.html">
>
> actualy works?? Looks like it has too many ../.. to me...
>
> I suspect (hope?) it could be advantageously replaced by {@link
> java.lang.management}.
>
>
> Similarly:
>
>   36  * <a
> href="{@docRoot}/java/lang/management/ManagementFactory.html#getPlatformMBeanServer()">
>   37  * java.lang.management.ManagementFactory.getPlatformMBeanServer</a>
>
> could probably be {@link
> java.lang.management.ManagementFactory#getPlatformMBeanServer()}
>
>
> This also reminds me that as part of the technical debt we might also
> think about replacing package.html files by their more modern
> package-info.java counterpart - but that's probably for another day...
>
>
> cheers,
>
> -- daniel
>
>
>
> On 10/05/2017 19:22, Roger Riggs wrote:
>> Please review corrections to broken javadoc links:
>>  - links to the serialization spec now in ./specs/serialization
>>  - links in java.lang to java/util/Spliterator
>>  - link in ModuleLayer to Classloader
>>  - Links using ../../../.. do not work well when they show up in some
>> indexes; they should use @docRoot
>>
>> webrev:
>> http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/
>>
>> Issue:
>>   https://bugs.openjdk.java.net/browse/JDK-8180082
>>
>> Thanks, Roger
>>
>

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

Re: RFR 9: 8180082 : Broken javadoc links

Magnus Ihse Bursie
In reply to this post by Brian Burkhalter-2
On 2017-05-10 23:05, Brian Burkhalter wrote:
> Hi Roger,
>
> Looks all right to me. I assume you will have already built the actual docs and clicked through the updated links. Always a bit painful …

Roger,

Did you test the actual links?

I found one needing updating:

In src/java.base/share/classes/java/io/ObjectStreamClass.java,
class.html#4100 should be updated to class.html#stream-unique-identifiers.

Also, the link in src/java.base/share/classes/java/lang/String.java
looks suspect. The text refers to Section 6.2 Stream Elements, but to
get there the link should go to protocol.html#stream-elements. Instead
it points to output.html, which is Section 2, Object Output Classes. I
can't really tell which is correct, but my guess is that the text is
correct and the link is not.

/Magnus

>
> Thanks,
>
> Brian
>
> On May 10, 2017, at 11:22 AM, Roger Riggs <[hidden email]> wrote:
>
>> Please review corrections to broken javadoc links:
>> - links to the serialization spec now in ./specs/serialization
>> - links in java.lang to java/util/Spliterator
>> - link in ModuleLayer to Classloader
>> - Links using ../../../.. do not work well when they show up in some indexes; they should use @docRoot
>>
>> webrev:
>>   http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/
>>
>> Issue:
>>   https://bugs.openjdk.java.net/browse/JDK-8180082

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

Re: RFR 9: 8180082 : Broken javadoc links

Daniel Fuchs
In reply to this post by roger riggs
Hi Roger,

Looks good!

Nit:
java/lang/management/package.html:
   38 conforms to the {@link javax.management JMX}
should probably use {@linkplain } instead.

(no need for a new webrev)

best regards,

-- daniel

On 11/05/2017 20:41, Roger Riggs wrote:

> Hi,
>
> Thanks for the review and suggestions.
> {@link ...} will work those links;  some hrefs will remain in cases
> where the link is to an "id" of some
> element that is not a method or field name.
>
> Webrev updated in place:
>     http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/
>
> Thanks, Roger
>
> On 5/11/2017 5:24 AM, Daniel Fuchs wrote:
>> Hi Roger,
>>
>> I'm surprised to see we have <a href=""...> style links in .java
>> files to link to package summary and java APIs for classes and
>> methods, when {@link } should work...
>>
>> For instance in this file:
>> http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/src/jdk.management/share/classes/com/sun/management/package-info.java.frames.html
>>
>>
>> Does:
>>
>>   29  * <a
>> href="{@docRoot}/../../../../api/java/lang/management/package-summary.html">
>>
>>
>> actualy works?? Looks like it has too many ../.. to me...
>>
>> I suspect (hope?) it could be advantageously replaced by {@link
>> java.lang.management}.
>>
>>
>> Similarly:
>>
>>   36  * <a
>> href="{@docRoot}/java/lang/management/ManagementFactory.html#getPlatformMBeanServer()">
>>
>>   37  * java.lang.management.ManagementFactory.getPlatformMBeanServer</a>
>>
>> could probably be {@link
>> java.lang.management.ManagementFactory#getPlatformMBeanServer()}
>>
>>
>> This also reminds me that as part of the technical debt we might also
>> think about replacing package.html files by their more modern
>> package-info.java counterpart - but that's probably for another day...
>>
>>
>> cheers,
>>
>> -- daniel
>>
>>
>>
>> On 10/05/2017 19:22, Roger Riggs wrote:
>>> Please review corrections to broken javadoc links:
>>>  - links to the serialization spec now in ./specs/serialization
>>>  - links in java.lang to java/util/Spliterator
>>>  - link in ModuleLayer to Classloader
>>>  - Links using ../../../.. do not work well when they show up in some
>>> indexes; they should use @docRoot
>>>
>>> webrev:
>>> http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/
>>>
>>> Issue:
>>>   https://bugs.openjdk.java.net/browse/JDK-8180082
>>>
>>> Thanks, Roger
>>>
>>
>

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

Re: RFR 9: 8180082 : Broken javadoc links

roger riggs
In reply to this post by Magnus Ihse Bursie
Hi Magnus,

Webrev updated:
    http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/


On 5/12/2017 4:26 AM, Magnus Ihse Bursie wrote:

> On 2017-05-10 23:05, Brian Burkhalter wrote:
>> Hi Roger,
>>
>> Looks all right to me. I assume you will have already built the
>> actual docs and clicked through the updated links. Always a bit
>> painful …
>
> Roger,
>
> Did you test the actual links?
Well, linklint tries; though the output is a bit clouded by the 7105
missing named anchors
and it did not complain about the missing #4100.

>
> I found one needing updating:
>
> In src/java.base/share/classes/java/io/ObjectStreamClass.java,
> class.html#4100 should be updated to
> class.html#stream-unique-identifiers.
yes, fixed
>
> Also, the link in src/java.base/share/classes/java/lang/String.java
> looks suspect. The text refers to Section 6.2 Stream Elements, but to
> get there the link should go to protocol.html#stream-elements. Instead
> it points to output.html, which is Section 2, Object Output Classes. I
> can't really tell which is correct, but my guess is that the text is
> correct and the link is not.
The current reference is to bullet 9 that describes procedurally how
serializationof String occurs.

The target you suggest in protocol.html describes the encoding and would
be ok too,
but for stability I'd leave it as is.

Is it ok to put in a <a id="java-lang-string-encoding"></a> anchor in
the output.md markdown
or what is the preferred markup?

Thanks, Roger


>
> /Magnus
>
>>
>> Thanks,
>>
>> Brian
>>
>> On May 10, 2017, at 11:22 AM, Roger Riggs <[hidden email]>
>> wrote:
>>
>>> Please review corrections to broken javadoc links:
>>> - links to the serialization spec now in ./specs/serialization
>>> - links in java.lang to java/util/Spliterator
>>> - link in ModuleLayer to Classloader
>>> - Links using ../../../.. do not work well when they show up in some
>>> indexes; they should use @docRoot
>>>
>>> webrev:
>>> http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/
>>>
>>> Issue:
>>>   https://bugs.openjdk.java.net/browse/JDK-8180082
>

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

Re: RFR 9: 8180082 : Broken javadoc links

Magnus Ihse Bursie


On 2017-05-12 17:23, Roger Riggs wrote:
> Hi Magnus,
>
> Webrev updated:
> http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/

Looks good to me.

>
>
>
> On 5/12/2017 4:26 AM, Magnus Ihse Bursie wrote:
>> On 2017-05-10 23:05, Brian Burkhalter wrote:
>>> Hi Roger,
>>>
>>> Looks all right to me. I assume you will have already built the
>>> actual docs and clicked through the updated links. Always a bit
>>> painful …
>>
>> Roger,
>>
>> Did you test the actual links?
> Well, linklint tries; though the output is a bit clouded by the 7105
> missing named anchors
> and it did not complain about the missing #4100.
>
>>
>> I found one needing updating:
>>
>> In src/java.base/share/classes/java/io/ObjectStreamClass.java,
>> class.html#4100 should be updated to
>> class.html#stream-unique-identifiers.
> yes, fixed
>>
>> Also, the link in src/java.base/share/classes/java/lang/String.java
>> looks suspect. The text refers to Section 6.2 Stream Elements, but to
>> get there the link should go to protocol.html#stream-elements.
>> Instead it points to output.html, which is Section 2, Object Output
>> Classes. I can't really tell which is correct, but my guess is that
>> the text is correct and the link is not.
> The current reference is to bullet 9 that describes procedurally how
> serializationof String occurs.
>
> The target you suggest in protocol.html describes the encoding and
> would be ok too,
> but for stability I'd leave it as is.
>
> Is it ok to put in a <a id="java-lang-string-encoding"></a> anchor in
> the output.md markdown
> or what is the preferred markup?

Yes, if you need to link to something other than a heading, that's what
you need to to. More modern pandocs support a more "markdownish" syntax
but that's not available for us right now.

/Magnus

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

Re: RFR 9: 8180082 : Broken javadoc links

Jonathan Gibbons
In reply to this post by Magnus Ihse Bursie
I can strongly recommend using link checker tools.

For a long time, linklint has been the recommendation. However, linklint
cannot cope with "id" attribute on tags that are not <a> tags. That's
legal in HTML 5, but linklint is an old tool.  There are newer tools out
there, for both online and offline use, but I haven't used them enough
to make a specific recommendation.

-- Jon


On 05/12/2017 01:26 AM, Magnus Ihse Bursie wrote:

> On 2017-05-10 23:05, Brian Burkhalter wrote:
>> Hi Roger,
>>
>> Looks all right to me. I assume you will have already built the
>> actual docs and clicked through the updated links. Always a bit
>> painful …
>
> Roger,
>
> Did you test the actual links?
>
> I found one needing updating:
>
> In src/java.base/share/classes/java/io/ObjectStreamClass.java,
> class.html#4100 should be updated to
> class.html#stream-unique-identifiers.
>
> Also, the link in src/java.base/share/classes/java/lang/String.java
> looks suspect. The text refers to Section 6.2 Stream Elements, but to
> get there the link should go to protocol.html#stream-elements. Instead
> it points to output.html, which is Section 2, Object Output Classes. I
> can't really tell which is correct, but my guess is that the text is
> correct and the link is not.
>
> /Magnus
>
>>
>> Thanks,
>>
>> Brian
>>
>> On May 10, 2017, at 11:22 AM, Roger Riggs <[hidden email]>
>> wrote:
>>
>>> Please review corrections to broken javadoc links:
>>> - links to the serialization spec now in ./specs/serialization
>>> - links in java.lang to java/util/Spliterator
>>> - link in ModuleLayer to Classloader
>>> - Links using ../../../.. do not work well when they show up in some
>>> indexes; they should use @docRoot
>>>
>>> webrev:
>>> http://cr.openjdk.java.net/~rriggs/webrev-broken-links-8180082/
>>>
>>> Issue:
>>>   https://bugs.openjdk.java.net/browse/JDK-8180082
>

Loading...