RFR: 8294156: Allow PassFailJFrame.Builder to create test UI [v2]

[Alexey Ivanov]

On Wed, 20 Sep 2023 18:12:25 GMT, Phil Race <prr at openjdk.org> wrote:

>>> Shouldn't we mention here a window added by `testUI` via builder?
>> 
>> I don't think it's necessary: the builder uses `addTestWindow` under the hood. It's the builder that requires documentation.
>> 
>> In fact, the entire class requires a bit of TLC for documentation. I even wrote some after Lawrence @lawrence-andrew created the first version of `PassFailJFrame` but I never finished it. Even this part was implemented nearly a year ago.
>> 
>> I plan to create a wiki page on the [client-libs wiki](https://wiki.openjdk.org/display/ClientLibs) to describe creating manual tests with `PassFailJFrame`.
>
>> > Shouldn't we mention here a window added by `testUI` via builder?
>> 
>> I don't think it's necessary: the builder uses `addTestWindow` under the hood. It's the builder that requires documentation.
>> 
>> In fact, the entire class requires a bit of TLC for documentation. I even wrote some after Lawrence @lawrence-andrew created the first version of `PassFailJFrame` but I never finished it. Even this part was implemented nearly a year ago.
>> 
>> I plan to create a wiki page on the [client-libs wiki](https://wiki.openjdk.org/display/ClientLibs) to describe creating manual tests with `PassFailJFrame`.
> 
> Just saw this, and it mirrors what I wrote in another PR that we need docs, but I believe they are best placed inside the source itself. Not everyone who can update this source can update the wiki.
> That doesn't preclude you from putting more examples on the wiki and a reference to it from the source but I still think there should be docs in the source.
> 
> Include how to use this feature and something like to the builder example you have here might be good too.

In fact, I started writing javadoc for `PassFailJFrame` while Lawrence and I discussed it. I explained how to use the framework. But I have never finished it to a PR-ready state.

As I noted in the [HTML enhancement PR](https://github.com/openjdk/jdk/pull/15660#discussion_r1338892141), I'd rather document both features together.

On the other hand, I would prefer integrating this so that people could use it already. In my opinion, this feature streamlines the usage of `PassFailJFrame`.

At the same time, the framework needs docs badly, especially as such rich features are added. And writing docs usually slips as other tasks come up.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/15665#discussion_r1338906945