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

[Lance Andersen]

Hi Jon

The changes provided  look reasonable
> On Aug 23, 2017, at 5:15 PM, Jonathan Gibbons <jonathan.gibbons at oracle.com> 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
> 
> 

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