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

[Jonathan Gibbons]

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