Add docs

Author: katcharov

driver-sync/src/test/functional/com/mongodb/client/unified/UnifiedTest.java

@@ -382,7 +382,7 @@ public void shouldPassAllOutcomes(
             if (isLastAttempt) {
                 throw e;
             }
-            
+
             ignoreRemaining.remove(testName);
             abort("Ignoring failure and retrying attempt " + attemptNumber);
         }

driver-sync/src/test/functional/com/mongodb/client/unified/UnifiedTestModifications.java

@@ -509,6 +509,12 @@ public TestApplicator when(final Supplier<Boolean> precondition) {
             return this;
         }
 
+        /**
+         * The modification, if it is a RETRY, will only be applied when the
+         * failure message contains the provided message fragment. If an
+         * {@code AssertionFailedError} occurs, and has a cause, the cause's
+         * message will be checked. Otherwise, the throwable will be checked.
+         */
         public TestApplicator whenFailureContains(final String messageFragment) {
             this.matchesThrowable = (final Throwable e) -> {
                 // inspect the cause for failed assertions with a cause
@@ -546,11 +552,15 @@ public enum Modifier {
          */
         SKIP,
         /**
-         * Retry the test on failure.
+         * Ignore results and retry the test on failure. Will not repeat the
+         * test if the test succeeds. Multiple copies of the test are used to
+         * facilitate retries.
          */
         RETRY,
         /**
-         * Retry the test multiple times, without ignoring failures.
+         * The test will be retried multiple times, without the results being
+         * ignored. This is a helper that can be used, in patches, to check
+         * if certain tests are (still) flaky.
          */
         FORCE_FLAKY,
     }