From 0fd04d18edbea17baf7fc79b09d1656afdabe148 Mon Sep 17 00:00:00 2001 From: Stuart Montgomery Date: Mon, 9 Dec 2024 19:30:25 -0800 Subject: [PATCH] Fix DocC warnings and errors, including those from SPI (#836) This includes a variety of cleanups and fixes to resolve DocC warnings and errors, including those which show up only when you manually include SPI declarations (by passing the `-include-spi-symbols` Swift compiler flag). I extracted some of these from #295, and found new ones. I still plan to pursue that PR, but reduce its focus to just enabling the SPI documentation flag in some local development workflows. In the mean time, this PR contains only documentation fixes. ### 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. --- Sources/Testing/Attachments/Attachment.swift | 10 ++-- Sources/Testing/Events/Event.swift | 7 ++- .../Event.HumanReadableOutputRecorder.swift | 6 +-- Sources/Testing/ExitTests/ExitTest.swift | 4 +- Sources/Testing/Issues/Issue.swift | 31 ++++++------ .../Test.Case.Generator.swift | 30 +++++------ .../Running/Configuration.TestFilter.swift | 2 +- Sources/Testing/Running/Configuration.swift | 7 +-- .../Testing/Running/Runner.Plan+Dumping.swift | 1 - Sources/Testing/Running/Runner.Plan.swift | 2 +- .../Testing/Support/CartesianProduct.swift | 20 ++++---- Sources/Testing/Test+Macro.swift | 50 +++++++++---------- .../Testing.docc/LimitingExecutionTime.md | 5 +- Sources/Testing/Testing.docc/Traits.md | 2 +- Sources/Testing/Testing.docc/Traits/Trait.md | 2 +- Sources/Testing/Traits/ConditionTrait.swift | 24 ++++----- Sources/Testing/Traits/TimeLimitTrait.swift | 4 +- .../TestSupport/TestingAdditions.swift | 20 ++++---- 18 files changed, 117 insertions(+), 110 deletions(-) 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,