Clarify the outcome of applying a timeLimit trait to a suite. (#1225)

Make it clearer that the time limit applies to each test or case in the
suite, not to the overall runtime of the test suite.

### Motivation:

I received feedback that a developer couldn't work out whether
`.timeLimit(_:)` on a suite limits each test, or the whole suite.

### Modifications:

- Add documentation that explains that the time limit applies to each
test or case in a parameterized test, when you apply it to a suite.
- Remove some passive-voice sentences in the same documents so that it's
clearer what a developer does, and what the testing library does for
them.

### Checklist:

- [X] Code and documentation should follow the style of the [Style
Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md).
- [X] If public symbols are renamed or modified, DocC references should
be updated.

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)
   }