On Wed, 20 Sep 2023 18:12:25 GMT, Phil Race <p...@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
