[6.2] Clarify the outcome of applying a timeLimit trait to a suite. (#1225) (#1229)

- **Explanation**:
Update the documentation for the `timeLimit` trait to clarify that
applying the trait to a suite means that each test in that suite gets
the time limit.

- **Scope**:
Documentation changes only.

- **Issues**:

- **Original PRs**:
#1225

- **Risk**:
Documentation changes only, so very low risk.

- **Testing**:
N/A

- **Reviewers**:
@stmontgomery

Author: iamleeg

Sources/Testing/Testing.docc/LimitingExecutionTime.md

@@ -40,22 +40,29 @@ hour (60 x 60 seconds) to execute, the task in which it's running is
 and the test fails with an issue of kind
 ``Issue/Kind-swift.enum/timeLimitExceeded(timeLimitComponents:)``.
 
-- Note: If multiple time limit traits apply to a test, the shortest time limit
-  is used.
+- Note: If multiple time limit traits apply to a test, the testing library uses
+  the shortest time limit.
 
 The testing library may adjust the specified time limit for performance reasons
 or to ensure tests have enough time to run. In particular, a granularity of (by
 default) one minute is applied to tests. The testing library can also be
 configured with a maximum time limit per test that overrides any applied time
 limit traits.
 
-### Time limits applied to test suites
+### Apply time limits to test suites
 
-When a time limit is applied to a test suite, it's recursively applied to all
-test functions and child test suites within that suite.
+When you apply a time limit to a test suite, the testing library recursively
+applies it to all test functions and child test suites within that suite.
+The time limit applies to each test in the test suite and any child test suites,
+or each test case for parameterized tests.
 
-### Time limits applied to parameterized tests
+For example, if a suite contains five tests and you apply a time limit trait
+with a duration of one minute, then each test in the suite may run for up to
+one minute.
 
-When a time limit is applied to a parameterized test function, it's applied to
-each invocation _separately_ so that if only some arguments cause failures, then
-successful arguments aren't incorrectly marked as failing too.
+### Apply time limits to parameterized tests
+
+When you apply a time limit to a parameterized test function, the testing
+library applies it to each invocation _separately_ so that if only some
+cases cause failures due to timeouts, then the testing library doesn't
+incorrectly mark successful cases as failing.

Sources/Testing/Traits/TimeLimitTrait.swift

@@ -83,6 +83,13 @@ extension Trait where Self == TimeLimitTrait {
   /// test cases individually. If a test has more than one time limit associated
   /// with it, the shortest one is used. A test run may also be configured with
   /// a maximum time limit per test case.
+  ///
+  /// If you apply this trait to a test suite, then it sets the time limit for
+  /// each test in the suite, or each test case in parameterized tests in the
+  /// suite.
+  /// For example, if a suite contains five tests and you apply a time limit trait
+  /// with a duration of one minute, then each test in the suite may run for up to
+  /// one minute.
   @_spi(Experimental)
   public static func timeLimit(_ timeLimit: Duration) -> Self {
     return Self(timeLimit: timeLimit)
@@ -116,6 +123,13 @@ extension Trait where Self == TimeLimitTrait {
   /// If a test is parameterized, this time limit is applied to each of its
   /// test cases individually. If a test has more than one time limit associated
   /// with it, the testing library uses the shortest time limit.
+  ///
+  /// If you apply this trait to a test suite, then it sets the time limit for
+  /// each test in the suite, or each test case in parameterized tests in the
+  /// suite.
+  /// For example, if a suite contains five tests and you apply a time limit trait
+  /// with a duration of one minute, then each test in the suite may run for up to
+  /// one minute.
   public static func timeLimit(_ timeLimit: Self.Duration) -> Self {
     return Self(timeLimit: timeLimit.underlyingDuration)
   }