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.
swiftlang · Dec 10, 2024 · 0fd04d1 · 0fd04d1
1 parent 906092d
commit 0fd04d1
Show file tree

Hide file tree

Showing 18 changed files with 117 additions and 110 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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<S>: 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<E1, E2>(
       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<E1, E2>(
       arguments collection: S,
       parameters: [Test.Parameter],

diff --git 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<Test.ID>) {
     self.init(_kind: .testIDs(Set(testIDs), membership: .excluding))
   }

diff --git 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
@@ -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
@@ -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
@@ -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<C1, C2>: 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<C1, C2>(_ collection1: C1, _ collection2: C2) -> CartesianProduct<C1, C2> where C1: Collection, C2: Collection {
   CartesianProduct(collection1: collection1, collection2: collection2)
 }
diff --git a/Sources/Testing/Test+Macro.swift b/Sources/Testing/Test+Macro.swift
@@ -220,14 +220,14 @@ public macro Test<C>(
 /// 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
 ///
 /// - <doc:DefiningTests>
+//
+// @Comment {
+//   - Bug: The testing library should support variadic generics.
+//     ([103416861](rdar://103416861))
+// }
 @attached(peer) public macro Test<C>(
   _ 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
 ///
 /// - <doc:DefiningTests>
+//
+// @Comment {
+//   - Bug: The testing library should support variadic generics.
+//     ([103416861](rdar://103416861))
+// }
 @attached(peer)
 @_documentation(visibility: private)
 public macro Test<C1, C2>(
@@ -301,14 +301,14 @@ public macro Test<C1, C2>(
 /// 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
 ///
 /// - <doc:DefiningTests>
+//
+// @Comment {
+//   - Bug: The testing library should support variadic generics.
+//     ([103416861](rdar://103416861))
+// }
 @attached(peer) public macro Test<C1, C2>(
   _ displayName: _const String? = nil,
   _ traits: any TestTrait...,
@@ -327,14 +327,14 @@ public macro Test<C1, C2>(
 /// 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
 ///
 /// - <doc:DefiningTests>
+//
+// @Comment {
+//   - Bug: The testing library should support variadic generics.
+//     ([103416861](rdar://103416861))
+// }
 @attached(peer)
 @_documentation(visibility: private)
 public macro Test<C1, C2>(
@@ -355,14 +355,14 @@ public macro Test<C1, C2>(
 /// 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
 ///
 /// - <doc:DefiningTests>
+//
+// @Comment {
+//   - Bug: The testing library should support variadic generics.
+//     ([103416861](rdar://103416861))
+// }
 @attached(peer) public macro Test<C1, C2>(
   _ displayName: _const String? = nil,
   _ traits: any TestTrait...,

diff --git 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
@@ -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
@@ -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