Fix DocC warnings and errors, including those from SPI

Sources/Testing/Attachments/Attachment.swift

@@ -111,11 +111,9 @@ 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.
-/// }
+//
+// 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

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:

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

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.

Sources/Testing/Issues/Issue.swift

@@ -49,12 +49,10 @@ 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.
-    /// }
+    //
+    // - 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 +335,10 @@ 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.
-    /// }
+    //
+    // - 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 +351,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:

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

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

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

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 {

Sources/Testing/Test+Macro.swift

@@ -220,14 +220,12 @@ 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>
+//
+// - Bug: The testing library should support variadic generics.
+//   ([103416861](rdar://103416861))
 @attached(peer) public macro Test<C>(
   _ displayName: _const String? = nil,
   _ traits: any TestTrait...,
@@ -301,14 +299,12 @@ 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>
+//
+// - 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...,
@@ -355,14 +351,12 @@ 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>
+//
+// - 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...,

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

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
 

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
 

Sources/Testing/Traits/ConditionTrait.swift

@@ -122,12 +122,10 @@ 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))
-  /// }
+  //
+  // - 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 +181,10 @@ 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))
-  /// }
+  //
+  // - 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,

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