RFR: 8355515: Clarify the purpose of forcePass() and forceFail() methods

[Alexey Ivanov]

On Wed, 7 May 2025 12:28:52 GMT, Manukumar V S <mvs at openjdk.org> wrote:

> Clarified the purpose of forcePass() and forceFail() methods and recommended usage of these methods.
> 
> forcePass() contained an incorrect sample; it's addressed by [JDK-8355441](https://bugs.openjdk.org/browse/JDK-8355441).
> 
> The description of forceFail() has been expanded, too.
> 
> 
> A new section in the description of the PassFailJFrame added to describe forcePass() and forceFail().

Changes requested by aivanov (Reviewer).

After reading the description again, I started to wonder which adverb suits better: [‘forcibly’](https://en.wiktionary.org/wiki/forcibly) or [‘forcefully’](https://en.wiktionary.org/wiki/forcefully). Does any native English speaker have an opinion?

test/jdk/java/awt/regtesthelpers/PassFailJFrame.java line 160:

> 158:  * the test will be forcefully Passed/Failed accordingly.
> 159:  * Code examples are given in the corresponding method javadoc.
> 160:  * <p>

Suggestion:

 *
 * <p id="forcePassAndFail">
 * For semi-automatic tests, use {@code forcePass} or
 * {@code forceFail} methods to forcibly pass or fail the test
 * when it's determined that the required conditions are already met
 * or cannot be met correspondingly.
 * These methods release {@code awaitAndCheck}, and
 * the test will complete successfully or fail.
 * <p>
 * Refer to examples of using these methods in the description of the
 * {@link #forcePass() forcePass} and {@link #forceFail() forceFail} methods.


The empty `<p>` in the end before a heading is redundant and will be ignored.

test/jdk/java/awt/regtesthelpers/PassFailJFrame.java line 1325:

> 1323:      * <p>
> 1324:      * Use this method in semi-automatic tests when
> 1325:      * the test determines that all/any of the conditions for passing the test are not met.

Suggestion:

     * <p>
     * Use this method in semi-automatic tests when
     * it is determined that the conditions for passing the test cannot be met.

I still don't like this phrase… but I can't come up with a different one.

test/jdk/java/awt/regtesthelpers/PassFailJFrame.java line 1342:

> 1340:      * <p>
> 1341:      * Use this method in semi-automatic tests when
> 1342:      * the test determines that all/any of the conditions for passing the test are not met.

Suggestion:

     * Use this method in semi-automatic tests when
     * it is determined that the conditions for passing the test cannot be met.

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

PR Review: https://git.openjdk.org/jdk/pull/25091#pullrequestreview-2846421361
PR Comment: https://git.openjdk.org/jdk/pull/25091#issuecomment-2886557839
PR Review Comment: https://git.openjdk.org/jdk/pull/25091#discussion_r2092914570
PR Review Comment: https://git.openjdk.org/jdk/pull/25091#discussion_r2092919697
PR Review Comment: https://git.openjdk.org/jdk/pull/25091#discussion_r2092931090