RFR: JDK-8273154: Provide a JavadocTester method for non-overlapping, unordered output matching [v6]

[Pavel Rappo]

On Tue, 9 Nov 2021 22:09:00 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a moderately simple improvement for `JavadocTester` and a related new test.
>> 
>> A new `OutputChecker` class is introduced that mostly supersedes the existing methods to check the output generated by javadoc and the standard doclet. A self-imposed restriction is that no existing tests are modified.
>> 
>> The new class can be used to check files generated by the doclet and the streams written by the tool. It can be configured to check for ordered output or not, overlapping output, and complete coverage, and can search for literal strings and regular expressions.  
>> 
>> There is a corresponding new test which is a non-standard use of `JavadocTester`, since it is designed to test `JavadocTester` itself, and not javadoc or the doclet.   (Quis custodiet ipsos custodes?)  Various methods are overridden so that the operation of the underlying methods can be checked.
>> 
>> Although it is a goal to NOT modify the code of any existing tests, it turns out to be reasonable to adapt some of the existing `check...` methods to use the new `OutputChecker`.  All javadoc tests pass, both locally and on all standard platforms.  Many/most uses of the existing `checkOutput` method provide "ordered" strings, and are candidates to use the new ordered check. But enough uses are _not_ ordered, so it is not reasonable to change the default at this time.  It is noted as a TODO to examine the appropriate test cases, so that we can decide whether to fix those tests and change the default.
>
> Jonathan Gibbons has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Merge remote-tracking branch 'origin/8273154.JavadocTester-checker' into 8273154.JavadocTester-checker
>  - Merge remote-tracking branch 'upstream/master' into 8273154.JavadocTester-checker

Looks good. I'm looking forward to using this in testing the snippets feature (JEP 413).

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

Marked as reviewed by prappo (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/5743