Update documentation comments in the code samples

Author: younata

proposals/testing/NNNN-polling-confirmations.md

@@ -139,18 +139,18 @@ testing library:
 /// Poll expression within the duration based on the given stop condition
 ///
 /// - Parameters:
-///   - comment: An optional comment to apply to any issues generated by this
-///     function.
+///   - comment: A user-specified comment describing this confirmation.
 ///   - stopCondition: When to stop polling.
 ///   - duration: The expected length of time to continue polling for.
-///     This value may not correspond to the wall-clock time that polling lasts
-///     for, especially on highly-loaded systems with a lot of tests running.
+///     This value does not incorporate the time to run `body`, and may not
+///     correspond to the wall-clock time that polling lasts for, especially on
+///     highly-loaded systems with a lot of tests running.
 ///     If nil, this uses whatever value is specified under the last
 ///     ``PollingConfirmationConfigurationTrait`` added to the test or suite
 ///     with a matching stopCondition.
 ///     If no such trait has been added, then polling will be attempted for
 ///     about 1 second before recording an issue.
-///     `duration` must be greater than 0.
+///     `duration` must be greater than or equal to `interval`.
 ///   - interval: The minimum amount of time to wait between polling attempts.
 ///     If nil, this uses whatever value is specified under the last
 ///     ``PollingConfirmationConfigurationTrait`` added to the test or suite
@@ -159,9 +159,10 @@ testing library:
 ///     1 millisecond between polling attempts.
 ///     `interval` must be greater than 0.
 ///   - isolation: The actor to which `body` is isolated, if any.
-///   - sourceLocation: The source location to whych any recorded issues should
-///     be attributed.
-///   - body: The function to invoke.
+///   - sourceLocation: The location in source where the confirmation was called.
+///   - body: The function to invoke. The expression is considered to pass if
+///     the `body` returns true. Similarly, the expression is considered to fail
+///     if `body` returns false.
 ///
 /// - Throws: A `PollingFailedError` if the `body` does not return true within
 ///   the polling duration.
@@ -184,18 +185,18 @@ public func confirmation(
 /// Confirm that some expression eventually returns a non-nil value
 ///
 /// - Parameters:
-///   - comment: An optional comment to apply to any issues generated by this
-///     function.
+///   - comment: A user-specified comment describing this confirmation.
 ///   - stopCondition: When to stop polling.
 ///   - duration: The expected length of time to continue polling for.
-///     This value may not correspond to the wall-clock time that polling lasts
-///     for, especially on highly-loaded systems with a lot of tests running.
+///     This value does not incorporate the time to run `body`, and may not
+///     correspond to the wall-clock time that polling lasts for, especially on
+///     highly-loaded systems with a lot of tests running.
 ///     If nil, this uses whatever value is specified under the last
 ///     ``PollingConfirmationConfigurationTrait`` added to the test or suite
 ///     with a matching stopCondition.
 ///     If no such trait has been added, then polling will be attempted for
 ///     about 1 second before recording an issue.
-///     `duration` must be greater than 0.
+///     `duration` must be greater than or equal to `interval`.
 ///   - interval: The minimum amount of time to wait between polling attempts.
 ///     If nil, this uses whatever value is specified under the last
 ///     ``PollingConfirmationConfigurationTrait`` added to the test or suite
@@ -204,9 +205,10 @@ public func confirmation(
 ///     1 millisecond between polling attempts.
 ///     `interval` must be greater than 0.
 ///   - isolation: The actor to which `body` is isolated, if any.
-///   - sourceLocation: The source location to whych any recorded issues should
-///     be attributed.
-///   - body: The function to invoke.
+///   - sourceLocation: The location in source where the confirmation was called.
+///   - body: The function to invoke. The expression is considered to pass if
+///     the `body` returns a non-nil value. Similarly, the expression is
+///     considered to fail if `body` returns nil.
 ///
 /// - Throws: A `PollingFailedError` if the `body` does not return true within
 ///   the polling duration.
@@ -240,17 +242,17 @@ how the confirmation should be handled.
 ```swift
 /// A type defining when to stop polling early.
 /// This also determines what happens if the duration elapses during polling.
-public enum PollingStopCondition: Sendable, Equatable {
-  /// Evaluates the expression until the first time it returns true.
-  /// If it does not pass once by the time the timeout is reached, then a
+public enum PollingStopCondition: Sendable, Equatable, Codable {
+  /// Evaluates the expression until the first time it passes
+  /// If it does not pass once by the time the duration is reached, then a
   /// failure will be reported.
   case firstPass
 
-  /// Evaluates the expression until the first time it returns false.
-  /// If the expression returns false, then a failure will be reported.
-  /// If the expression only returns true before the timeout is reached, then
+  /// Evaluates the expression until the first time it returns fails.
+  /// If the expression fails, then a failure will be reported.
+  /// If the expression only passes before the duration is reached, then
   /// no failure will be reported.
-  /// If the expression does not finish evaluating before the timeout is
+  /// If the expression does not finish evaluating before the duration is
   /// reached, then a failure will be reported.
   case stopsPassing
 }
@@ -360,7 +362,7 @@ extension Trait where Self == PollingConfirmationConfigurationTrait {
   ///     lasts for, especially on highly-loaded systems with a lot of tests
   ///     running.
   ///     if nil, polling will be attempted for approximately 1 second.
-  ///     `duration` must be greater than 0.
+  ///     `duration` must be greater than `interval`.
   ///   - interval: The minimum amount of time to wait between polling
   ///     attempts.
   ///     If nil, polling will wait at least 1 millisecond between polling