RFR: JDK-8186684: Fix broken links in java.base API docs

[Xueming Shen]

    src/java.base/share/classes/java/util/jar/package-info.java
    src/java.base/share/classes/java/util/zip/Deflater.java
    src/java.base/share/classes/java/util/zip/Inflater.java

looks good.

On 8/23/17, 2:15 PM, Jonathan Gibbons wrote:
> Please review a reasonably simple patch to fix most of the broken 
> links in the API docs for java.base module.
> All the fixes are in the small "typo" category, and so should not 
> materially affect the specification.
>
> I've provided a copy of the API, in case folk want to test the updated 
> links.  The affected files are in the following packages:
>
>    java.lang
>    java.lang.invoke
>    java.lang.module
>    java.net
>    java.nio.channels.spi
>    java.nio.file
>    java.nio.file.attribute
>    java.util
>    java.util.concurrent
>    java.util.jar
>    java.util.stream
>    java.util.zip
>
> JBS: https://bugs.openjdk.java.net/browse/JDK-8186684
> Webrev: http://cr.openjdk.java.net/~jjg/8186684/webrev.00/index.html
> API: http://cr.openjdk.java.net/~jjg/8186684/api.00/overview-summary.html
>
> Here are some notes on the files that have been modified:
>
> In many cases, the problem was a combination of a number of factors:
> 1. The doc comments did not use an arg list when {@link}ing to a method.
> 2. javadoc is supposed to give a warning when an arg list is omitted, 
> but does not
> 3. javadoc will sometimes choose to link to a private member, even 
> when it is not being
>     documented, when better alternatives exist.  For example, javadoc 
> will
>     currently prefer to link {@link #parent}  to "private Object 
> parent;" instead of
>     "public Object Parent();}
> javadoc needs to be fixed, but so too should the doc comments.
>
> This applies to the following files:
>
>    src/java.base/share/classes/java/lang/BootstrapMethodError.java
>    src/java.base/share/classes/java/lang/ModuleLayer.java
>    src/java.base/share/classes/java/lang/ProcessBuilder.java
>    src/java.base/share/classes/java/lang/invoke/MethodHandle.java
>    src/java.base/share/classes/java/lang/invoke/VarHandle.java
>    src/java.base/share/classes/java/lang/module/ModuleDescriptor.java
>    src/java.base/share/classes/java/nio/file/FileSystems.java
>    src/java.base/share/classes/java/nio/file/attribute/AclEntry.java
>    src/java.base/share/classes/java/util/ArrayDeque.java
>
>
> In this file, in the absence of an explicit arg list, javadoc ended up 
> linking
> #dropArgumentsToMatch to a private method with the right name.
> The fix is to specify the arg list.
>
>    src/java.base/share/classes/java/lang/invoke/MethodHandles.java
>
>
> There's another category of errors, related to the use of relative 
> links in
> <a href=".....">  The problem occurs when such links are used in text
> that may appear in different contexts. There are currently two scenarios
> in which this occurs.
> 1. In the "first sentence" of a description ... the first sentence may be
> copied to appear in summary tables in other pages.
> 2. In descriptions that will be copied into other pages using 
> {@inheritDoc}.
> In both cases, the relative link may be OK when appearing in its original
> context, but may become broken when used in other contexts.
> javadoc has never claimed to "fix up" such constructs, although it
> would be a good Enhancement for it to do so, or to provide a way of
> achieving the same effect. The solution, for now, is to use a reference
> that will worth wherever the text is evaluated. Right now, the 
> suggested form
> is <a href="{@docRoot}/path/to/file.html#anchor">.
> It's clunky, but it works.
>
> This applies to the following files:
>
>    src/java.base/share/classes/java/lang/module/Configuration.java
>    src/java.base/share/classes/java/util/Collection.java
>
> This file has an explicit @see to a private method.  The reference is 
> deleted.
>
>    src/java.base/share/classes/java/net/URLStreamHandler.java
>
> An anchor is replaced. It used to exist, and somewhere along the line, 
> it got removed,
> causing broken links.
>
>    
> src/java.base/share/classes/java/nio/channels/spi/AbstractInterruptibleChannel.java
>    
> src/java.base/share/classes/java/nio/channels/spi/AbstractSelector.java
>
>
> This file had a case-mismatch between the definition and reference of 
> the link.
> This was tolerated in HTML 4.01, but not allowed in HTML5.
>
>    src/java.base/share/classes/java/util/Calendar.java
>
> An explicit arg list has to be supplied for a constructor to prevent 
> javadoc from
> using a private/undocumented one. There were two to choose from ... a 
> general
> one, and one that defaulted some args. I linked to the more general one.
>
>    
> src/java.base/share/classes/java/util/concurrent/ForkJoinWorkerThread.java
>
>
> javadoc has vacillated in recent releases on the anchor name to use for a
> package's description. We've settled on "package.description". Some files
> needed to be fixed up.
>
>    src/java.base/share/classes/java/util/jar/package-info.java
>    src/java.base/share/classes/java/util/zip/Deflater.java
>    src/java.base/share/classes/java/util/zip/Inflater.java
>
> In this case, although the anchor name did not exist it was close to one
> that did, suggesting a typo, but the text of the link suggested a 
> different
> anchor. Paul recommened the choice here:
>
>    src/java.base/share/classes/java/util/stream/package-info.java
>
>