Hi Jon The changes provided look reasonable > On Aug 23, 2017, at 5:15 PM, Jonathan Gibbons <jonathan.gibb...@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.ander...@oracle.com <mailto:lance.ander...@oracle.com>
