diff --git a/Sources/Testing/Attachments/Attachment.swift b/Sources/Testing/Attachments/Attachment.swift index d79a43fcb..93ae53c73 100644 --- a/Sources/Testing/Attachments/Attachment.swift +++ b/Sources/Testing/Attachments/Attachment.swift @@ -111,11 +111,11 @@ extension Attachment where AttachableValue == AnyAttachable { /// events of kind ``Event/Kind/valueAttached(_:)``. Test tools authors who use /// `@_spi(ForToolsIntegrationOnly)` will see instances of this type when /// handling those events. -/// -/// @Comment { -/// Swift's type system requires that this type be at least as visible as -/// `Event.Kind.valueAttached(_:)`, otherwise it would be declared private. -/// } +// +// @Comment { +// Swift's type system requires that this type be at least as visible as +// `Event.Kind.valueAttached(_:)`, otherwise it would be declared private. +// } @_spi(Experimental) @_spi(ForToolsIntegrationOnly) public struct AnyAttachable: AttachableContainer, Copyable, Sendable { #if !SWT_NO_LAZY_ATTACHMENTS diff --git a/Sources/Testing/Events/Event.swift b/Sources/Testing/Events/Event.swift index d76346623..60e564d5a 100644 --- a/Sources/Testing/Events/Event.swift +++ b/Sources/Testing/Events/Event.swift @@ -462,8 +462,11 @@ extension Event.Kind { /// This is the last event posted before ``Runner/run()`` returns. case runEnded - /// Snapshots an ``Event.Kind``. - /// - Parameter kind: The original ``Event.Kind`` to snapshot. + /// Initialize an instance of this type by snapshotting the specified event + /// kind. + /// + /// - Parameters: + /// - kind: The original event kind to snapshot. public init(snapshotting kind: Event.Kind) { switch kind { case .testDiscovered: diff --git a/Sources/Testing/Events/Recorder/Event.HumanReadableOutputRecorder.swift b/Sources/Testing/Events/Recorder/Event.HumanReadableOutputRecorder.swift index ab1f56702..9468d55ae 100644 --- a/Sources/Testing/Events/Recorder/Event.HumanReadableOutputRecorder.swift +++ b/Sources/Testing/Events/Recorder/Event.HumanReadableOutputRecorder.swift @@ -74,9 +74,9 @@ extension Event { /// Initialize a new human-readable event recorder. /// /// Output from the testing library is converted to "messages" using the - /// ``Event/HumanReadableOutputRecorder/record(_:)`` function. The format of - /// those messages is, as the type's name suggests, not meant to be - /// machine-readable and is subject to change. + /// ``Event/HumanReadableOutputRecorder/record(_:in:verbosity:)`` function. + /// The format of those messages is, as the type's name suggests, not meant + /// to be machine-readable and is subject to change. public init() {} } } diff --git a/Sources/Testing/ExitTests/ExitTest.swift b/Sources/Testing/ExitTests/ExitTest.swift index f21104f31..39a0ea550 100644 --- a/Sources/Testing/ExitTests/ExitTest.swift +++ b/Sources/Testing/ExitTests/ExitTest.swift @@ -53,8 +53,8 @@ public struct ExitTest: Sendable, ~Copyable { /// this property to determine what information you need to preserve from your /// child process. /// - /// The value of this property always includes ``Result/exitCondition`` even - /// if the test author does not specify it. + /// The value of this property always includes ``ExitTestArtifacts/exitCondition`` + /// even if the test author does not specify it. /// /// Within a child process running an exit test, the value of this property is /// otherwise unspecified. diff --git a/Sources/Testing/Issues/Issue.swift b/Sources/Testing/Issues/Issue.swift index 68f9bb7b4..731a240d1 100644 --- a/Sources/Testing/Issues/Issue.swift +++ b/Sources/Testing/Issues/Issue.swift @@ -49,12 +49,12 @@ public struct Issue: Sendable { /// /// - Parameters: /// - timeLimitComponents: The time limit reached by the test. - /// - /// @Comment { - /// - Bug: The associated value of this enumeration case should be an - /// instance of `Duration`, but the testing library's deployment target - /// predates the introduction of that type. - /// } + // + // @Comment { + // - Bug: The associated value of this enumeration case should be an + // instance of `Duration`, but the testing library's deployment target + // predates the introduction of that type. + // } indirect case timeLimitExceeded(timeLimitComponents: (seconds: Int64, attoseconds: Int64)) /// A known issue was expected, but was not recorded. @@ -337,12 +337,12 @@ extension Issue.Kind { /// /// - Parameters: /// - timeLimitComponents: The time limit reached by the test. - /// - /// @Comment { - /// - Bug: The associated value of this enumeration case should be an - /// instance of `Duration`, but the testing library's deployment target - /// predates the introduction of that type. - /// } + // + // @Comment { + // - Bug: The associated value of this enumeration case should be an + // instance of `Duration`, but the testing library's deployment target + // predates the introduction of that type. + // } indirect case timeLimitExceeded(timeLimitComponents: (seconds: Int64, attoseconds: Int64)) /// A known issue was expected, but was not recorded. @@ -355,8 +355,11 @@ extension Issue.Kind { /// within the tests being run. case system - /// Snapshots an ``Issue.Kind``. - /// - Parameter kind: The original ``Issue.Kind`` to snapshot. + /// Initialize an instance of this type by snapshotting the specified issue + /// kind. + /// + /// - Parameters: + /// - kind: The original issue kind to snapshot. public init(snapshotting kind: Issue.Kind) { self = switch kind { case .unconditional: diff --git a/Sources/Testing/Parameterization/Test.Case.Generator.swift b/Sources/Testing/Parameterization/Test.Case.Generator.swift index 123f5c712..d4d583e48 100644 --- a/Sources/Testing/Parameterization/Test.Case.Generator.swift +++ b/Sources/Testing/Parameterization/Test.Case.Generator.swift @@ -13,11 +13,11 @@ extension Test.Case { /// a known collection of argument values. /// /// Instances of this type can be iterated over multiple times. - /// - /// @Comment { - /// - Bug: The testing library should support variadic generics. - /// ([103416861](rdar://103416861)) - /// } + // + // @Comment { + // - Bug: The testing library should support variadic generics. + // ([103416861](rdar://103416861)) + // } struct Generator: Sendable where S: Sequence & Sendable, S.Element: Sendable { /// The underlying sequence of argument values. /// @@ -146,11 +146,11 @@ extension Test.Case { /// /// This initializer overload is specialized for sequences of 2-tuples to /// efficiently de-structure their elements when appropriate. - /// - /// @Comment { - /// - Bug: The testing library should support variadic generics. - /// ([103416861](rdar://103416861)) - /// } + // + // @Comment { + // - Bug: The testing library should support variadic generics. + // ([103416861](rdar://103416861)) + // } private init( sequence: S, parameters: [Test.Parameter], @@ -184,11 +184,11 @@ extension Test.Case { /// /// This initializer overload is specialized for collections of 2-tuples to /// efficiently de-structure their elements when appropriate. - /// - /// @Comment { - /// - Bug: The testing library should support variadic generics. - /// ([103416861](rdar://103416861)) - /// } + // + // @Comment { + // - Bug: The testing library should support variadic generics. + // ([103416861](rdar://103416861)) + // } init( arguments collection: S, parameters: [Test.Parameter], diff --git a/Sources/Testing/Running/Configuration.TestFilter.swift b/Sources/Testing/Running/Configuration.TestFilter.swift index ec2427348..7ef1fb08c 100644 --- a/Sources/Testing/Running/Configuration.TestFilter.swift +++ b/Sources/Testing/Running/Configuration.TestFilter.swift @@ -116,7 +116,7 @@ extension Configuration.TestFilter { /// of test IDs. /// /// - Parameters: - /// - selection: A set of test IDs to be excluded. + /// - testIDs: A set of test IDs to be excluded. public init(excluding testIDs: some Collection) { self.init(_kind: .testIDs(Set(testIDs), membership: .excluding)) } diff --git a/Sources/Testing/Running/Configuration.swift b/Sources/Testing/Running/Configuration.swift index be9101d24..3f9ed67f4 100644 --- a/Sources/Testing/Running/Configuration.swift +++ b/Sources/Testing/Running/Configuration.swift @@ -69,8 +69,8 @@ public struct Configuration: Sendable { /// The conditions under which test iterations should continue. /// /// If the value of this property is `nil`, a test plan will be run - /// ``count`` times regardless of whether or not issues are encountered - /// while running. + /// ``maximumIterationCount`` times regardless of whether or not issues are + /// encountered while running. public var continuationCondition: ContinuationCondition? /// The maximum number of times the test run should iterate. @@ -88,7 +88,8 @@ public struct Configuration: Sendable { /// - continuationCondition: The conditions under which test iterations /// should continue. If `nil`, the iterations should continue /// unconditionally `count` times. - /// - count: The maximum number of times the test run should iterate. + /// - maximumIterationCount: The maximum number of times the test run + /// should iterate. public static func repeating(_ continuationCondition: ContinuationCondition? = nil, maximumIterationCount: Int) -> Self { Self(continuationCondition: continuationCondition, maximumIterationCount: maximumIterationCount) } diff --git a/Sources/Testing/Running/Runner.Plan+Dumping.swift b/Sources/Testing/Running/Runner.Plan+Dumping.swift index dc8d0e23c..1303fcb91 100644 --- a/Sources/Testing/Running/Runner.Plan+Dumping.swift +++ b/Sources/Testing/Running/Runner.Plan+Dumping.swift @@ -96,7 +96,6 @@ extension Runner.Plan { /// `true`, `Swift.dump(_:to:name:indent:maxDepth:maxItems:)` is called /// instead of the testing library's implementation. /// - indent: How many spaces to indent each level of text in the dump. - /// - depth: How many levels deep `stepGraph` is in the total graph. /// /// This function produces a detailed dump of the runner plan suitable for /// inclusion in diagnostics or for display as part of a command-line diff --git a/Sources/Testing/Running/Runner.Plan.swift b/Sources/Testing/Running/Runner.Plan.swift index 33398be59..7553acf6e 100644 --- a/Sources/Testing/Running/Runner.Plan.swift +++ b/Sources/Testing/Running/Runner.Plan.swift @@ -445,7 +445,7 @@ extension Runner.Plan.Step { } extension Runner.Plan.Action { - /// A serializable snapshot of a ``Runner/Plan-swift.struct/Step/Action`` + /// A serializable snapshot of a ``Runner/Plan-swift.struct/Action`` /// instance. @_spi(ForToolsIntegrationOnly) public enum Snapshot: Sendable, Codable { diff --git a/Sources/Testing/Support/CartesianProduct.swift b/Sources/Testing/Support/CartesianProduct.swift index 43d92e462..07b164eb5 100644 --- a/Sources/Testing/Support/CartesianProduct.swift +++ b/Sources/Testing/Support/CartesianProduct.swift @@ -17,11 +17,11 @@ /// `[(1, "a"), (1, "b"), (1, "c"), (2, "a"), (2, "b"), ... (3, "c")]`. /// /// This type is not part of the public interface of the testing library. -/// -/// @Comment { -/// - Bug: The testing library should support variadic generics. -/// ([103416861](rdar://103416861)) -/// } +// +// @Comment { +// - Bug: The testing library should support variadic generics. +// ([103416861](rdar://103416861)) +// } struct CartesianProduct: LazySequenceProtocol where C1: Collection, C2: Collection { fileprivate var collection1: C1 fileprivate var collection2: C2 @@ -63,11 +63,11 @@ extension CartesianProduct: Sendable where C1: Sendable, C2: Sendable {} /// while `collection2` is iterated `collection1.count` times. /// /// For more information on Cartesian products, see ``CartesianProduct``. -/// -/// @Comment { -/// - Bug: The testing library should support variadic generics. -/// ([103416861](rdar://103416861)) -/// } +// +// @Comment { +// - Bug: The testing library should support variadic generics. +// ([103416861](rdar://103416861)) +// } func cartesianProduct(_ collection1: C1, _ collection2: C2) -> CartesianProduct where C1: Collection, C2: Collection { CartesianProduct(collection1: collection1, collection2: collection2) } diff --git a/Sources/Testing/Test+Macro.swift b/Sources/Testing/Test+Macro.swift index 891b37fe3..6f8536ac1 100644 --- a/Sources/Testing/Test+Macro.swift +++ b/Sources/Testing/Test+Macro.swift @@ -220,14 +220,14 @@ public macro Test( /// During testing, the associated test function is called once for each element /// in `collection`. /// -/// @Comment { -/// - Bug: The testing library should support variadic generics. -/// ([103416861](rdar://103416861)) -/// } -/// /// ## See Also /// /// - +// +// @Comment { +// - Bug: The testing library should support variadic generics. +// ([103416861](rdar://103416861)) +// } @attached(peer) public macro Test( _ displayName: _const String? = nil, _ traits: any TestTrait..., @@ -273,14 +273,14 @@ extension Test { /// During testing, the associated test function is called once for each pair of /// elements in `collection1` and `collection2`. /// -/// @Comment { -/// - Bug: The testing library should support variadic generics. -/// ([103416861](rdar://103416861)) -/// } -/// /// ## See Also /// /// - +// +// @Comment { +// - Bug: The testing library should support variadic generics. +// ([103416861](rdar://103416861)) +// } @attached(peer) @_documentation(visibility: private) public macro Test( @@ -301,14 +301,14 @@ public macro Test( /// During testing, the associated test function is called once for each pair of /// elements in `collection1` and `collection2`. /// -/// @Comment { -/// - Bug: The testing library should support variadic generics. -/// ([103416861](rdar://103416861)) -/// } -/// /// ## See Also /// /// - +// +// @Comment { +// - Bug: The testing library should support variadic generics. +// ([103416861](rdar://103416861)) +// } @attached(peer) public macro Test( _ displayName: _const String? = nil, _ traits: any TestTrait..., @@ -327,14 +327,14 @@ public macro Test( /// During testing, the associated test function is called once for each element /// in `zippedCollections`. /// -/// @Comment { -/// - Bug: The testing library should support variadic generics. -/// ([103416861](rdar://103416861)) -/// } -/// /// ## See Also /// /// - +// +// @Comment { +// - Bug: The testing library should support variadic generics. +// ([103416861](rdar://103416861)) +// } @attached(peer) @_documentation(visibility: private) public macro Test( @@ -355,14 +355,14 @@ public macro Test( /// During testing, the associated test function is called once for each element /// in `zippedCollections`. /// -/// @Comment { -/// - Bug: The testing library should support variadic generics. -/// ([103416861](rdar://103416861)) -/// } -/// /// ## See Also /// /// - +// +// @Comment { +// - Bug: The testing library should support variadic generics. +// ([103416861](rdar://103416861)) +// } @attached(peer) public macro Test( _ displayName: _const String? = nil, _ traits: any TestTrait..., diff --git a/Sources/Testing/Testing.docc/LimitingExecutionTime.md b/Sources/Testing/Testing.docc/LimitingExecutionTime.md index 2b992b108..151b52028 100644 --- a/Sources/Testing/Testing.docc/LimitingExecutionTime.md +++ b/Sources/Testing/Testing.docc/LimitingExecutionTime.md @@ -19,8 +19,9 @@ resources to complete, may rely on downloaded data from a server, or may otherwise be dependent on external factors. If a test may hang indefinitely or may consume too many system resources to -complete effectively, consider setting a time limit for it so that it's marked as failing if it runs for an excessive amount of time. Use the -``Trait/timeLimit(_:)`` trait as an upper bound: +complete effectively, consider setting a time limit for it so that it's marked +as failing if it runs for an excessive amount of time. Use the +``Trait/timeLimit(_:)-4kzjp`` trait as an upper bound: ```swift @Test(.timeLimit(.minutes(60)) diff --git a/Sources/Testing/Testing.docc/Traits.md b/Sources/Testing/Testing.docc/Traits.md index db8455fc5..3fe181bb9 100644 --- a/Sources/Testing/Testing.docc/Traits.md +++ b/Sources/Testing/Testing.docc/Traits.md @@ -30,7 +30,7 @@ behavior of test functions. - ``Trait/disabled(_:sourceLocation:)`` - ``Trait/disabled(if:_:sourceLocation:)`` - ``Trait/disabled(_:sourceLocation:_:)`` -- ``Trait/timeLimit(_:)`` +- ``Trait/timeLimit(_:)-4kzjp`` ### Running tests serially or in parallel diff --git a/Sources/Testing/Testing.docc/Traits/Trait.md b/Sources/Testing/Testing.docc/Traits/Trait.md index 1528ec1b4..d5a110602 100644 --- a/Sources/Testing/Testing.docc/Traits/Trait.md +++ b/Sources/Testing/Testing.docc/Traits/Trait.md @@ -22,7 +22,7 @@ See https://swift.org/CONTRIBUTORS.txt for Swift project authors ### Limiting the running time of tests -- ``Trait/timeLimit(_:)`` +- ``Trait/timeLimit(_:)-4kzjp`` ### Running tests serially or in parallel diff --git a/Sources/Testing/Traits/ConditionTrait.swift b/Sources/Testing/Traits/ConditionTrait.swift index 09c8909dc..8e1117f8a 100644 --- a/Sources/Testing/Traits/ConditionTrait.swift +++ b/Sources/Testing/Traits/ConditionTrait.swift @@ -122,12 +122,12 @@ extension Trait where Self == ConditionTrait { /// /// - 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)) - /// } + // + // @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, @@ -183,12 +183,12 @@ extension Trait where Self == ConditionTrait { /// /// - 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)) - /// } + // + // @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, diff --git a/Sources/Testing/Traits/TimeLimitTrait.swift b/Sources/Testing/Traits/TimeLimitTrait.swift index fe1d7f787..2dc86de20 100644 --- a/Sources/Testing/Traits/TimeLimitTrait.swift +++ b/Sources/Testing/Traits/TimeLimitTrait.swift @@ -12,7 +12,7 @@ /// /// To add this trait to a test, use one of the following functions: /// -/// - ``Trait/timeLimit(_:)`` +/// - ``Trait/timeLimit(_:)-4kzjp`` @available(_clockAPI, *) public struct TimeLimitTrait: TestTrait, SuiteTrait { /// A type representing the duration of a time limit applied to a test. @@ -189,7 +189,7 @@ extension Test { /// /// Time limits are associated with tests using this trait: /// - /// - ``Trait/timeLimit(_:)`` + /// - ``Trait/timeLimit(_:)-4kzjp`` /// /// If a test has more than one time limit associated with it, the value of /// this property is the shortest one. If a test has no time limits associated diff --git a/Tests/TestingTests/TestSupport/TestingAdditions.swift b/Tests/TestingTests/TestSupport/TestingAdditions.swift index 0f0d4641a..906bf737a 100644 --- a/Tests/TestingTests/TestSupport/TestingAdditions.swift +++ b/Tests/TestingTests/TestSupport/TestingAdditions.swift @@ -157,11 +157,11 @@ extension Test { /// - testFunction: The function to call when running this test. During /// testing, this function is called once for each element in /// `collection`. - /// - /// @Comment { - /// - Bug: The testing library should support variadic generics. - /// ([103416861](rdar://103416861)) - /// } + // + // @Comment { + // - Bug: The testing library should support variadic generics. + // ([103416861](rdar://103416861)) + // } init( _ traits: any TestTrait..., arguments collection: C, @@ -186,11 +186,11 @@ extension Test { /// - testFunction: The function to call when running this test. During /// testing, this function is called once for each pair of elements in /// `collection1` and `collection2`. - /// - /// @Comment { - /// - Bug: The testing library should support variadic generics. - /// ([103416861](rdar://103416861)) - /// } + // + // @Comment { + // - Bug: The testing library should support variadic generics. + // ([103416861](rdar://103416861)) + // } init( _ traits: any TestTrait..., arguments collection1: C1, _ collection2: C2,