Please review a small but slightly tricky fix related to broken links on
the serialized-form page.
The underlying problem was that the doclet was generating bad links when
an @see tag
was referencing a member that was not itself being documented. For
example, the following
will normally cause a broken link because privateMethod will not
normally be included in the
documentation.
public class C {
/** Text.
* @see #privateMethod()
*/
public void publicMethod() { }
private void privateMethod() { }
}
There is a spectrum of possible solutions, some more complicated than
others.
The approach here is to fix the perceived original intent of the code
which is to detect
when the link will not be generated, and in that case, just write the
label, without
any enclosing link.
This is done by creating and using a new method in Utils that carefully
tries to determine
whether the link should be generated. It's not ideal, and may need to be
refined in due course,
as we identify more test cases, but it is arguably "good enough" for
now, in that all existing
tests continue to pass, as well as some new test cases that mimic the
problem as originally
discovered. It is possible that we might be able to simplify this code,
in time, by using
information in the recently-new VisibleMemberTable.
With regard to the original problem of broken links on the
serialized-form page in the
JDK API, the number of broken links has gone down by about 15%.
With respect to the webrev, there is some minor cleanup, but primarily,
the expression
on HtmlDocletWriter:916 has been replaced by a call to a new method in
Utils, that
provides a more nuanced determination of whether the link should be
generated
or not.
The new test creates various test scenarios and runs them through
javadoc. It is worth
noting that by default *all* javadoc tests using JavadocTester now run a
link checker
(checkLinks) unless it is explicitly disabled, and that ensures no
regressions in the
output generated in any other of the javadoc tests.
JBS: https://bugs.openjdk.java.net/browse/JDK-8207214
Webrev: http://cr.openjdk.java.net/~jjg/8207214/webrev.00/index.html
-- Jon
