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
