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.

test/langtools/jdk/javadoc/doclet/testMethodCommentAlgorithm/TestMethodCommentsAlgorithm.java line 395:

> 393:         String testSrc = System.getProperty("test.src");
> 394:         if (testSrc == null) {
> 395:             // shouldn't happen

Purely FYI, it could happen if the class is run directly, without `jtreg`.
That being said, very few people do that these days.
No change necessary,

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17280#discussion_r1443390237