Cleaning recently changed docs (#924)

Improving the style and explanation of recent additions to the
documentation.

The recent changes to test traits are great, and come with some very
nice documentation. I've done what I can to improve the style and the
wording to make it easier to understand, and to make the style
consistent with other documentation in the project.

Changed the documentation for `Trait` and associated types.

There are no behavioral changes in this PR, but I hope that the existing
behavior is easier to use with better documentation.

- [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.

Sources/Testing/Testing.docc/Traits.md

@@ -10,14 +10,14 @@ See https://swift.org/LICENSE.txt for license information
 See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 -->
 
-Add traits to tests to annotate them or customize their behavior.
+Annotate test functions and suites, and customize their behavior.
 
 ## Overview
 
 Pass built-in traits to test functions or suite types to comment, categorize, 
-classify, and modify runtime behaviors. You can also use the ``Trait``, ``TestTrait``, 
-and ``SuiteTrait`` protocols to create your own types that customize the 
-behavior of test functions.
+classify, and modify the runtime behavior of test suites and test functions.
+Implement the ``TestTrait``, and ``SuiteTrait`` protocols to create your own
+types that customize the behavior of your tests.
 
 ## Topics
 

Sources/Testing/Testing.docc/Traits/Trait.md

@@ -20,34 +20,25 @@ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 - ``Trait/disabled(if:_:sourceLocation:)``
 - ``Trait/disabled(_:sourceLocation:_:)``
 
-### Limiting the running time of tests
-
-- ``Trait/timeLimit(_:)``
-
-### Running tests serially or in parallel
+### Controlling how tests are run
 
+- ``Trait/timeLimit(_:)-4kzjp``
 - ``Trait/serialized``
-
-### Categorizing tests
+ 
+### Categorizing tests and adding information
 
 - ``Trait/tags(_:)``
+- ``Trait/comments``
 
 ### Associating bugs
 
 - ``Trait/bug(_:_:)``
 - ``Trait/bug(_:id:_:)-10yf5``
 - ``Trait/bug(_:id:_:)-3vtpl``
 
-### Adding information to tests
-
-- ``Trait/comments``
-
-### Preparing internal state
-
-- ``Trait/prepare(for:)-3s3zo``
-
-### Providing custom execution scope for tests
+### Running code before and after a test or suite
 
 - ``TestScoping``
 - ``Trait/scopeProvider(for:testCase:)-cjmg``
 - ``Trait/TestScopeProvider``
+- ``Trait/prepare(for:)-3s3zo``

Sources/Testing/Traits/Bug.swift

@@ -8,15 +8,15 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-/// A type representing a bug report tracked by a test.
+/// A type that represents a bug report tracked by a test.
 ///
 /// To add this trait to a test, use one of the following functions:
 ///
 /// - ``Trait/bug(_:_:)``
 /// - ``Trait/bug(_:id:_:)-10yf5``
 /// - ``Trait/bug(_:id:_:)-3vtpl``
 public struct Bug {
-  /// A URL linking to more information about the bug, if available.
+  /// A URL that links to more information about the bug, if available.
   ///
   /// The value of this property represents a URL conforming to
   /// [RFC 3986](https://www.ietf.org/rfc/rfc3986.txt).
@@ -59,42 +59,42 @@ extension Bug: TestTrait, SuiteTrait {
 }
 
 extension Trait where Self == Bug {
-  /// Construct a bug to track with a test.
+  /// Constructs a bug to track with a test.
   ///
   /// - Parameters:
-  ///   - url: A URL referring to this bug in the associated bug-tracking
+  ///   - url: A URL that refers to this bug in the associated bug-tracking
   ///     system.
   ///   - title: Optionally, the human-readable title of the bug.
   ///
-  /// - Returns: An instance of ``Bug`` representing the specified bug.
+  /// - Returns: An instance of ``Bug`` that represents the specified bug.
   public static func bug(_ url: _const String, _ title: Comment? = nil) -> Self {
     Self(url: url, title: title)
   }
 
-  /// Construct a bug to track with a test.
+  /// Constructs a bug to track with a test.
   ///
   /// - Parameters:
-  ///   - url: A URL referring to this bug in the associated bug-tracking
+  ///   - url: A URL that refers to this bug in the associated bug-tracking
   ///     system.
   ///   - id: The unique identifier of this bug in its associated bug-tracking
   ///     system.
   ///   - title: Optionally, the human-readable title of the bug.
   ///
-  /// - Returns: An instance of ``Bug`` representing the specified bug.
+  /// - Returns: An instance of ``Bug`` that represents the specified bug.
   public static func bug(_ url: _const String? = nil, id: some Numeric, _ title: Comment? = nil) -> Self {
     Self(url: url, id: String(describing: id), title: title)
   }
 
-  /// Construct a bug to track with a test.
+  /// Constructs a bug to track with a test.
   ///
   /// - Parameters:
-  ///   - url: A URL referring to this bug in the associated bug-tracking
+  ///   - url: A URL that refers to this bug in the associated bug-tracking
   ///     system.
   ///   - id: The unique identifier of this bug in its associated bug-tracking
   ///     system.
   ///   - title: Optionally, the human-readable title of the bug.
   ///
-  /// - Returns: An instance of ``Bug`` representing the specified bug.
+  /// - Returns: An instance of ``Bug`` that represents the specified bug.
   public static func bug(_ url: _const String? = nil, id: _const String, _ title: Comment? = nil) -> Self {
     Self(url: url, id: id, title: title)
   }

Sources/Testing/Traits/Comment.swift

@@ -8,22 +8,21 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-/// A type representing a comment related to a test.
+/// A type that represents a comment related to a test.
 ///
-/// This type may be used to provide context or background information about a
+/// Use this type to provide context or background information about a
 /// test's purpose, explain how a complex test operates, or include details
 /// which may be helpful when diagnosing issues recorded by a test.
 ///
 /// To add a comment to a test or suite, add a code comment before its `@Test`
 /// or `@Suite` attribute. See <doc:AddingComments> for more details.
 ///
-/// - Note: This type is not intended to reference bugs related to a test.
-///   Instead, use ``Trait/bug(_:_:)``, ``Trait/bug(_:id:_:)-10yf5``, or
-///   ``Trait/bug(_:id:_:)-3vtpl``.
+/// - Note: To reference bugs related to a test, use ``Trait/bug(_:_:)``,
+///   ``Trait/bug(_:id:_:)-10yf5``, or ``Trait/bug(_:id:_:)-3vtpl``.
 public struct Comment: RawRepresentable, Sendable {
-  /// The single comment string contained in this instance.
+  /// The single comment string that this comment contains.
   ///
-  /// To obtain the complete set of comments applied to a test, see
+  /// To get the complete set of comments applied to a test, see
   /// ``Test/comments``.
   public var rawValue: String
 

Sources/Testing/Traits/ConditionTrait.swift

@@ -8,8 +8,8 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-/// A type that defines a condition which must be satisfied for a test to be
-/// enabled.
+/// A type that defines a condition which must be satisfied for the testing
+/// library to enable a test.
 ///
 /// To add this trait to a test, use one of the following functions:
 ///
@@ -19,10 +19,10 @@
 /// - ``Trait/disabled(if:_:sourceLocation:)``
 /// - ``Trait/disabled(_:sourceLocation:_:)``
 public struct ConditionTrait: TestTrait, SuiteTrait {
-  /// An enumeration describing the kinds of conditions that can be represented
-  /// by an instance of this type.
+  /// An enumeration that describes the conditions that an instance of this type
+  /// can represent.
   enum Kind: Sendable {
-    /// The trait is conditional on the result of calling a function.
+    /// Enabling the test is conditional on the result of calling a function.
     ///
     /// - Parameters:
     ///   - body: The function to call. The result of this function determines
@@ -39,7 +39,8 @@ public struct ConditionTrait: TestTrait, SuiteTrait {
     ///   - body: The function to call. The result of this function determines
     ///     whether or not the condition was met.
     ///
-    /// - Returns: An instance of this type.
+    /// - Returns: A trait that marks a test's enabled status as the result of
+    ///            calling a function.
     static func conditional(_ body: @escaping @Sendable () async throws -> Bool) -> Self {
       conditional { () -> (Bool, comment: Comment?) in
         return (try await body(), nil)
@@ -49,14 +50,14 @@ public struct ConditionTrait: TestTrait, SuiteTrait {
     /// The trait is unconditional and always has the same result.
     ///
     /// - Parameters:
-    ///   - value: Whether or not the condition was met.
+    ///   - value: Whether or not the test is enabled.
     case unconditional(_ value: Bool)
   }
 
-  /// The kind of condition represented by this instance.
+  /// The kind of condition represented by this trait.
   var kind: Kind
 
-  /// Whether or not this trait has a condition that is evaluated at runtime.
+  /// Whether this trait's condition is constant, or evaluated at runtime.
   ///
   /// If this trait was created using a function such as
   /// ``disabled(_:sourceLocation:)`` that unconditionally enables or disables a
@@ -77,7 +78,7 @@ public struct ConditionTrait: TestTrait, SuiteTrait {
 
   public var comments: [Comment]
 
-  /// The source location where this trait was specified.
+  /// The source location where this trait is specified.
   public var sourceLocation: SourceLocation
 
   public func prepare(for test: Test) async throws {
@@ -110,24 +111,23 @@ public struct ConditionTrait: TestTrait, SuiteTrait {
 // MARK: -
 
 extension Trait where Self == ConditionTrait {
-  /// Construct a condition trait that causes a test to be disabled if it
-  /// returns `false`.
+  /// Constructs a condition trait that disables a test if it returns `false`.
   ///
   /// - Parameters:
-  ///   - condition: A closure containing the trait's custom condition logic. If
-  ///     this closure returns `true`, the test is allowed to run. Otherwise,
-  ///     the test is skipped.
-  ///   - comment: An optional, user-specified comment describing this trait.
+  ///   - condition: A closure that contains the trait's custom condition logic.
+  ///     If this closure returns `true`, the trait allows the test to run.
+  ///     Otherwise, the testing library skips the test.
+  ///   - comment: An optional comment that describes this trait.
   ///   - sourceLocation: The source location of the trait.
   ///
-  /// - Returns: An instance of ``ConditionTrait`` that will evaluate the
-  ///   specified closure.
-  ///
-  /// @Comment {
-  ///   - Bug: `condition` cannot be `async` without making this function
-  ///     `async` even though `condition` is not evaluated locally.
-  ///     ([103037177](rdar://103037177))
-  /// }
+  /// - Returns: An instance of ``ConditionTrait`` that evaluates the
+  ///   closure you provide.
+  //
+  // @Comment {
+  //   - Bug: `condition` cannot be `async` without making this function
+  //     `async` even though `condition` is not evaluated locally.
+  //     ([103037177](rdar://103037177))
+  // }
   public static func enabled(
     if condition: @autoclosure @escaping @Sendable () throws -> Bool,
     _ comment: Comment? = nil,
@@ -136,18 +136,17 @@ extension Trait where Self == ConditionTrait {
     Self(kind: .conditional(condition), comments: Array(comment), sourceLocation: sourceLocation)
   }
 
-  /// Construct a condition trait that causes a test to be disabled if it
-  /// returns `false`.
+  /// Constructs a condition trait that disables a test if it returns `false`.
   ///
   /// - Parameters:
-  ///   - comment: An optional, user-specified comment describing this trait.
+  ///   - comment: An optional comment that describes this trait.
   ///   - sourceLocation: The source location of the trait.
-  ///   - condition: A closure containing the trait's custom condition logic. If
-  ///     this closure returns `true`, the test is allowed to run. Otherwise,
-  ///     the test is skipped.
+  ///   - condition: A closure that contains the trait's custom condition logic.
+  ///     If this closure returns `true`, the trait allows the test to run.
+  ///     Otherwise, the testing library skips the test.
   ///
-  /// - Returns: An instance of ``ConditionTrait`` that will evaluate the
-  ///   specified closure.
+  /// - Returns: An instance of ``ConditionTrait`` that evaluates the
+  ///   closure you provide.
   public static func enabled(
     _ comment: Comment? = nil,
     sourceLocation: SourceLocation = #_sourceLocation,
@@ -156,13 +155,13 @@ extension Trait where Self == ConditionTrait {
     Self(kind: .conditional(condition), comments: Array(comment), sourceLocation: sourceLocation)
   }
 
-  /// Construct a condition trait that disables a test unconditionally.
+  /// Constructs a condition trait that disables a test unconditionally.
   ///
   /// - Parameters:
-  ///   - comment: An optional, user-specified comment describing this trait.
+  ///   - comment: An optional comment that describes this trait.
   ///   - sourceLocation: The source location of the trait.
   ///
-  /// - Returns: An instance of ``ConditionTrait`` that will always disable the
+  /// - Returns: An instance of ``ConditionTrait`` that always disables the
   ///   test to which it is added.
   public static func disabled(
     _ comment: Comment? = nil,
@@ -171,24 +170,23 @@ extension Trait where Self == ConditionTrait {
     Self(kind: .unconditional(false), comments: Array(comment), sourceLocation: sourceLocation)
   }
 
-  /// Construct a condition trait that causes a test to be disabled if it
-  /// returns `true`.
+  /// Constructs a condition trait that disables a test if its value is true.
   ///
   /// - Parameters:
-  ///   - condition: A closure containing the trait's custom condition logic. If
-  ///     this closure returns `false`, the test is allowed to run. Otherwise,
-  ///     the test is skipped.
-  ///   - comment: An optional, user-specified comment describing this trait.
+  ///   - condition: A closure that contains the trait's custom condition logic.
+  ///     If this closure returns `false`, the trait allows the test to run.
+  ///     Otherwise, the testing library skips the test.
+  ///   - comment: An optional comment that describes this trait.
   ///   - sourceLocation: The source location of the trait.
   ///
-  /// - Returns: An instance of ``ConditionTrait`` that will evaluate the
-  ///   specified closure.
-  ///
-  /// @Comment {
-  ///   - Bug: `condition` cannot be `async` without making this function
-  ///     `async` even though `condition` is not evaluated locally.
-  ///     ([103037177](rdar://103037177))
-  /// }
+  /// - Returns: An instance of ``ConditionTrait`` that evaluates the
+  ///   closure you provide.
+  //
+  // @Comment {
+  //   - Bug: `condition` cannot be `async` without making this function
+  //     `async` even though `condition` is not evaluated locally.
+  //     ([103037177](rdar://103037177))
+  // }
   public static func disabled(
     if condition: @autoclosure @escaping @Sendable () throws -> Bool,
     _ comment: Comment? = nil,
@@ -197,17 +195,16 @@ extension Trait where Self == ConditionTrait {
     Self(kind: .conditional { !(try condition()) }, comments: Array(comment), sourceLocation: sourceLocation)
   }
 
-  /// Construct a condition trait that causes a test to be disabled if it
-  /// returns `true`.
+  /// Constructs a condition trait that disables a test if its value is true.
   ///
   /// - Parameters:
-  ///   - comment: An optional, user-specified comment describing this trait.
+  ///   - comment: An optional comment that describes this trait.
   ///   - sourceLocation: The source location of the trait.
-  ///   - condition: A closure containing the trait's custom condition logic. If
-  ///     this closure returns `false`, the test is allowed to run. Otherwise,
-  ///     the test is skipped.
+  ///   - condition: A closure that contains the trait's custom condition logic.
+  ///     If this closure returns `false`, the trait allows the test to run.
+  ///     Otherwise, the testing library skips the test.
   ///
-  /// - Returns: An instance of ``ConditionTrait`` that will evaluate the
+  /// - Returns: An instance of ``ConditionTrait`` that evaluates the
   ///   specified closure.
   public static func disabled(
     _ comment: Comment? = nil,

Sources/Testing/Traits/ParallelizationTrait.swift

@@ -8,8 +8,10 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-/// A type that affects whether or not a test or suite is parallelized.
+/// A type that defines whether the testing library runs this test serially
+/// or in parallel.
 ///
+<<<<<<< HEAD
 /// When added to a parameterized test function, this trait causes that test to
 /// run its cases serially instead of in parallel. When applied to a
 /// non-parameterized test function, this trait has no effect. When applied to a
@@ -19,10 +21,20 @@
 /// This trait is recursively applied: if it is applied to a suite, any
 /// parameterized tests or test suites contained in that suite are also
 /// serialized (as are any tests contained in those suites, and so on.)
+=======
+/// When you add this trait to a parameterized test function, that test runs its
+/// cases serially instead of in parallel. This trait has no effect when you
+/// apply it to a non-parameterized test function.
+///
+/// When you add this trait to a test suite, that suite runs its
+/// contained test functions (including their cases, when parameterized) and
+/// sub-suites serially instead of in parallel. If the sub-suites have children,
+/// they also run serially.
+>>>>>>> 44684c1 (Cleaning recently changed docs (#924))
 ///
 /// This trait does not affect the execution of a test relative to its peers or
-/// to unrelated tests. This trait has no effect if test parallelization is
-/// globally disabled (by, for example, passing `--no-parallel` to the
+/// to unrelated tests. This trait has no effect if you disable test
+/// parallelization globally (for example, by passing `--no-parallel` to the
 /// `swift test` command.)
 ///
 /// To add this trait to a test, use ``Trait/serialized``.