RFR: 8310277: jdk/javadoc/doclet/testMethodCommentAlgorithm/TestMethodCommentsAlgorithm.java fails with IllegalStateException

[Jonathan Gibbons]

On Fri, 5 Jan 2024 13:52:23 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> This PR improves diagnostic output and behaviour of the `TestMethodCommentsAlgorithm` test in environments that do not meet that test's expectations.
> 
> The test assumes that a correct source file for `java.lang.Object` is available nearby. While the test verified that assumption, it didn't verify it deep enough. The issue described in the linked bug report seems to be that a directory that looks like a source directory does not contain that source file.
> 
> The solution is to check the assumptions more thoroughly. Note that if the assumptions aren't met, the test will be skipped, but it will not fail. Some tools display a skipped test as **passed**, which could be misleading. If I were the original bug reporter, I'd investigate why the source file for `java.lang.Object` is missing.
> 
> As for exception messages, I tried my best to make them helpful. That said, test exception messages are not user-level error messages. The stacktrace of an exception is supposed to be analysed in conjunction with the source that threw that exception.

Nice.

Always good to see improved/simplified/cleaned-up code.

-------------

Marked as reviewed by jjg (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17280#pullrequestreview-1806886989