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

Backport-of: 1a97eb429b520b7c4e625b97553c954d065c00cb

Author: GoeLin

test/jdk/java/awt/regtesthelpers/PassFailJFrame.java

@@ -150,6 +150,17 @@
  * Before returning from {@code awaitAndCheck}, the framework disposes of
  * all the windows and frames.
  *
+ * <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.
+ *
  * <h2 id="sampleManualTest">Sample Manual Test</h2>
  * A simple test would look like this:
  * {@snippet id='sampleManualTestCode' lang='java':
@@ -1310,14 +1321,34 @@ public static void forcePass() {
     }
 
     /**
-     *  Forcibly fail the test.
+     * Forcibly fail the test.
+     * <p>
+     * Use this method in semi-automatic tests when
+     * it is determined that the conditions for passing the test cannot be met.
+     * <p>
+     * <strong>Do not use</strong> this method in cases where a resource is unavailable or a
+     * feature isn't supported, throw {@code jtreg.SkippedException} instead.
+     *
+     * <p>A sample usage can be found in
+     * <a href="https://github.com/openjdk/jdk/blob/0844745e7bd954a96441365f8010741ec1c29dbf/test/jdk/javax/swing/JScrollPane/AcceleratedWheelScrolling/HorizScrollers.java#L180">{@code
+     * HorizScrollers.java}</a>
      */
     public static void forceFail() {
         forceFail("forceFail called");
     }
 
     /**
-     *  Forcibly fail the test and provide a reason.
+     * Forcibly fail the test and provide a reason.
+     * <p>
+     * Use this method in semi-automatic tests when
+     * it is determined that the conditions for passing the test cannot be met.
+     * <p>
+     * <strong>Do not use</strong> this method in cases where a resource is unavailable or a
+     * feature isn't supported, throw {@code jtreg.SkippedException} instead.
+     *
+     * <p>A sample usage can be found in
+     * <a href="https://github.com/openjdk/jdk/blob/7283c8b075aa289dbb9cb80f6937b3349c8d4769/test/jdk/java/awt/FileDialog/SaveFileNameOverrideTest.java#L86">{@code
+     * SaveFileNameOverrideTest.java}</a>
      *
      * @param reason the reason why the test is failed
      */