RFR: 8217034, , JavadocTester should check for missing files by default

[Jonathan Gibbons]

Please review a mostly "test only" fix to have JavadocTester treat links 
to missing files in the generated output as an error.

Currently, it detects and reports such files, but they are not treated 
as serious enough to cause the test to fail.

The primary fix to JavadocTester is a trivial one-liner, to bump the 
error count when missing files are found.

The catch is that doing so causes a number of tests to fail, which need 
to be fixed up. Most of these are "benign" failures, caused by issues in 
the way that the test was written, without expecting that links would 
ever be validated. In one case, the problem is in the javadoc tool 
itself, in which the "wrong" stylesheet is written into a redirect 
fiile. The fault there is mostly benign as well, since no stylesheet is 
actually required, but it is enough to cause a link checker to notice.

Here is an explanation of the edits:


test/langtools/jdk/javadoc/lib/javadoc/tester/JavadocTester.java

     The one-line change to treat links to missing files as a serious error

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexRedirectWriter.java

     Use the correct stylesheet in the redirect file. The difference is 
when a non-default stylesheet is given on the command line. This is at 
best a workaround solution. Arguably a better solution is to make it so 
that if no stylesheet(s) are given to Head.java, then no links to 
stylesheets are generated, but that is a more pervasive change that is 
out of scope for this mostly test-only fix.

test/langtools/jdk/javadoc/doclet/testBreakIterator/TestBreakIterator.java
test/langtools/jdk/javadoc/doclet/testBreakIterator/pkg/BreakIteratorTest.java

     The test generates a reference to a file that is not generated. The 
code is modified to reference a similar file that is generated.

test/langtools/jdk/javadoc/doclet/testDocRootInlineTag/TestDocRootInlineTag.java
test/langtools/jdk/javadoc/doclet/testDocRootInlineTag/TestDocRootTag.java

     Same as previous. The test generates a reference to a file that is 
not generated. The code is modified to reference a similar file that is 
generated.

test/langtools/jdk/javadoc/doclet/testDocRootLink/TestDocRootLink.java

     For this one, the automatic link check is disabled. There are 
details given in the test itself. Because of the pattern of the bad 
links, it does not seem appropriate to synthesize targets for the links, 
as is done in other cases.

test/langtools/jdk/javadoc/doclet/testHtmlLandmarkRegions/TestHtmlLandmarkRegions.java
test/langtools/jdk/javadoc/doclet/testIndexWithModules/TestIndexWithModules.java

     There's something going on here that seems to be a different 
problem. Filed JDK-8217013. The link checker is disabled in this test 
until 8217013 is fixed.

test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOption.java

     The example code has toy/bad links. The automatic link checker is 
disabled for those instances where the toy links cause the test to fail.

test/langtools/jdk/javadoc/doclet/testOptions/TestOptions.java

     This is the test that fails if the src/.../IndexRedirectWriter is 
not updated. It tests the stylesheet options that cause the "wrong" 
stylesheet to be generated in the index. It seems appropriate to tag 
this bug (and just this bug) as the test for the change to the src file.

test/langtools/jdk/javadoc/doclet/testRelativeLinks/TestRelativeLinks.java

     This test has a bunch of toy links that don't exist, and which 
cannot easily be generated by javadoc tool. Since the test is 
specifically about testing the handling of different sorts of links, it 
seems better to synthesize the missing/expected files rather than 
disable the link checker for this test.


test/langtools/jdk/javadoc/doclet/testCopyFiles/packages/p2/doc-files/theme.css

     For this test, we just create/use a dummy empty file in the repo 
that is enough to keep the link checker happy.


-----

-- Jon

JBS: https://bugs.openjdk.java.net/browse/JDK-8217034
Webrev: http://cr.openjdk.java.net/~jjg/8217034/webrev.00



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190114/2a459b37/attachment.html>