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

[Jonathan Gibbons]

On Wed, 20 Oct 2021 00:04:48 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> test/langtools/jdk/javadoc/lib/javadoc/tester/JavadocTester.java line 953:
>> 
>>> 951:          * @param file the file
>>> 952:          */
>>> 953:         public OutputChecker(String file) {
>> 
>> Given JDK-8274172, consider using java.nio.file.Path instead of String here. Using Path for files and String for target strings reduces potential for confusion.
>
> I'll investigate, but IIRC there is broad precedent for using `String file` to simplify the call site, avoiding boilerplate `Path.of`.

I looked at this, including just adding a path-based overload.

In general, I am a big proponent of using more specific types instead of strings, but the prevailing pattern in `JavadocTester` is to use strings for "paths relative to the most recent output directory".  Internally, `Path` is used more specifically for paths that have been resolved relative to the output directory, etc. so switching to `Path` in the public API would be less convenient for use sites, and would lead to ambiguities that would need to be addressed in the implementation.

TL:DR; this might be worth additional consideration down the road, but not as part of this work.

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

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