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

[Jonathan Gibbons]

Updated webrev to accommodate the recent refactoring of JavadocTester. 
The only difference is that one-line change that was previously in 
JavadocTester is now in LinkChecker.

-- Jon

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



On 01/14/2019 04:46 PM, Jonathan Gibbons wrote:
>
> 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/20190115/958d9d4b/attachment.html>