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

[Pavel Rappo]

On Wed, 29 Sep 2021 03:45:39 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 with a new target base due to a merge or a rebase. The pull request now contains two commits:
> 
>  - Merge with upstream/master
>  - JDK-8273154: Provide a JavadocTester method for non-overlapping, unordered output matching

Unrelated to this PR. Every time I see these lines in JavadocTester, I cannot help thinking that we could use more specific APIs:

    public static final String FS = System.getProperty("file.separator");
    public static final String PS = System.getProperty("path.separator");
    public static final String NL = System.getProperty("line.separator");
    public static final String thisRelease = System.getProperty("java.specification.version");

The above lines can be translated into:

    public static final String FS = java.io.File.separator;
    public static final String PS = java.io.File.pathSeparator;
    public static final String NL = System.lineSeparator();
    public static final String thisRelease = String.valueOf(Runtime.version().feature());

I note that neither `PS` nor `thisRelease` seem to be currently used.

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

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