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

[Pavel Rappo]

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.

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

Commit messages:
 - Initial commit

Changes: https://git.openjdk.org/jdk/pull/17280/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17280&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8310277
  Stats: 122 lines in 1 file changed: 44 ins; 45 del; 33 mod
  Patch: https://git.openjdk.org/jdk/pull/17280.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17280/head:pull/17280

PR: https://git.openjdk.org/jdk/pull/17280