RFR: 8340785: Update description of PassFailJFrame and samples

[Alexey Ivanov]

On Tue, 24 Sep 2024 15:51:09 GMT, Alexey Ivanov <aivanov at openjdk.org> wrote:

> I re-worked the entire description of `PassFailJFrame`:
> 
> Add description of what UI elements it provides and how to interact with them.
> Add anchors for linking to the sections.
> 
> Use `{@snippet}` instead of `<pre>{@code}</pre>` for sample code.
> Use method references instead of lambdas in samples.
> Document required jtreg tags to use `PassFailJFrame`.
> Rename `SampleOldManualTest` to `ObsoleteManualTest`.
> 
> Provide an overview of `Builder` methods to configure `PassFailJFrame`.
> 
> As in #21145, the generated javadoc [PassFailJFrame.html](https://cr.openjdk.org/~aivanov/PassFailJFrame/api/PassFailJFrame.html) could be easier to read and review.
> 
> The current version of the generated docs contains changes from #21145 and this PR. The PRs can be integrated independently.

There are still some missing parts, like more details on different kinds of `testUI` overloads and support for multiple windows.

At the same time, the description is close to comprehensive, the javadoc comment for the `PassFailJFrame` takes more than 200 lines.

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

PR Comment: https://git.openjdk.org/jdk/pull/21162#issuecomment-2371711426