Skip to content

Commit 0fd04d1

Browse files
stmontgomerystmontgomery
authored
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.
1 parent 906092d commit 0fd04d1

File tree

18 files changed

+117
-110
lines changed

18 files changed

+117
-110
lines changed

‎Sources/Testing/Attachments/Attachment.swift

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -111,11 +111,11 @@ extension Attachment where AttachableValue == AnyAttachable {
111111
/// events of kind ``Event/Kind/valueAttached(_:)``. Test tools authors who use
112112
/// `@_spi(ForToolsIntegrationOnly)` will see instances of this type when
113113
/// handling those events.
114-
///
115-
/// @Comment {
116-
/// Swift's type system requires that this type be at least as visible as
117-
/// `Event.Kind.valueAttached(_:)`, otherwise it would be declared private.
118-
/// }
114+
//
115+
// @Comment {
116+
// Swift's type system requires that this type be at least as visible as
117+
// `Event.Kind.valueAttached(_:)`, otherwise it would be declared private.
118+
// }
119119
@_spi(Experimental) @_spi(ForToolsIntegrationOnly)
120120
public struct AnyAttachable: AttachableContainer, Copyable, Sendable {
121121
#if !SWT_NO_LAZY_ATTACHMENTS

‎Sources/Testing/Events/Event.swift

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -462,8 +462,11 @@ extension Event.Kind {
462462
/// This is the last event posted before ``Runner/run()`` returns.
463463
case runEnded
464464

465-
/// Snapshots an ``Event.Kind``.
466-
/// - Parameter kind: The original ``Event.Kind`` to snapshot.
465+
/// Initialize an instance of this type by snapshotting the specified event
466+
/// kind.
467+
///
468+
/// - Parameters:
469+
/// - kind: The original event kind to snapshot.
467470
public init(snapshotting kind: Event.Kind) {
468471
switch kind {
469472
case .testDiscovered:

‎Sources/Testing/Events/Recorder/Event.HumanReadableOutputRecorder.swift

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -74,9 +74,9 @@ extension Event {
7474
/// Initialize a new human-readable event recorder.
7575
///
7676
/// Output from the testing library is converted to "messages" using the
77-
/// ``Event/HumanReadableOutputRecorder/record(_:)`` function. The format of
78-
/// those messages is, as the type's name suggests, not meant to be
79-
/// machine-readable and is subject to change.
77+
/// ``Event/HumanReadableOutputRecorder/record(_:in:verbosity:)`` function.
78+
/// The format of those messages is, as the type's name suggests, not meant
79+
/// to be machine-readable and is subject to change.
8080
public init() {}
8181
}
8282
}

‎Sources/Testing/ExitTests/ExitTest.swift

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,8 +53,8 @@ public struct ExitTest: Sendable, ~Copyable {
5353
/// this property to determine what information you need to preserve from your
5454
/// child process.
5555
///
56-
/// The value of this property always includes ``Result/exitCondition`` even
57-
/// if the test author does not specify it.
56+
/// The value of this property always includes ``ExitTestArtifacts/exitCondition``
57+
/// even if the test author does not specify it.
5858
///
5959
/// Within a child process running an exit test, the value of this property is
6060
/// otherwise unspecified.

‎Sources/Testing/Issues/Issue.swift

Lines changed: 17 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -49,12 +49,12 @@ public struct Issue: Sendable {
4949
///
5050
/// - Parameters:
5151
/// - timeLimitComponents: The time limit reached by the test.
52-
///
53-
/// @Comment {
54-
/// - Bug: The associated value of this enumeration case should be an
55-
/// instance of `Duration`, but the testing library's deployment target
56-
/// predates the introduction of that type.
57-
/// }
52+
//
53+
// @Comment {
54+
// - Bug: The associated value of this enumeration case should be an
55+
// instance of `Duration`, but the testing library's deployment target
56+
// predates the introduction of that type.
57+
// }
5858
indirect case timeLimitExceeded(timeLimitComponents: (seconds: Int64, attoseconds: Int64))
5959

6060
/// A known issue was expected, but was not recorded.
@@ -337,12 +337,12 @@ extension Issue.Kind {
337337
///
338338
/// - Parameters:
339339
/// - timeLimitComponents: The time limit reached by the test.
340-
///
341-
/// @Comment {
342-
/// - Bug: The associated value of this enumeration case should be an
343-
/// instance of `Duration`, but the testing library's deployment target
344-
/// predates the introduction of that type.
345-
/// }
340+
//
341+
// @Comment {
342+
// - Bug: The associated value of this enumeration case should be an
343+
// instance of `Duration`, but the testing library's deployment target
344+
// predates the introduction of that type.
345+
// }
346346
indirect case timeLimitExceeded(timeLimitComponents: (seconds: Int64, attoseconds: Int64))
347347

348348
/// A known issue was expected, but was not recorded.
@@ -355,8 +355,11 @@ extension Issue.Kind {
355355
/// within the tests being run.
356356
case system
357357

358-
/// Snapshots an ``Issue.Kind``.
359-
/// - Parameter kind: The original ``Issue.Kind`` to snapshot.
358+
/// Initialize an instance of this type by snapshotting the specified issue
359+
/// kind.
360+
///
361+
/// - Parameters:
362+
/// - kind: The original issue kind to snapshot.
360363
public init(snapshotting kind: Issue.Kind) {
361364
self = switch kind {
362365
case .unconditional:

‎Sources/Testing/Parameterization/Test.Case.Generator.swift

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,11 @@ extension Test.Case {
1313
/// a known collection of argument values.
1414
///
1515
/// Instances of this type can be iterated over multiple times.
16-
///
17-
/// @Comment {
18-
/// - Bug: The testing library should support variadic generics.
19-
/// ([103416861](rdar://103416861))
20-
/// }
16+
//
17+
// @Comment {
18+
// - Bug: The testing library should support variadic generics.
19+
// ([103416861](rdar://103416861))
20+
// }
2121
struct Generator<S>: Sendable where S: Sequence & Sendable, S.Element: Sendable {
2222
/// The underlying sequence of argument values.
2323
///
@@ -146,11 +146,11 @@ extension Test.Case {
146146
///
147147
/// This initializer overload is specialized for sequences of 2-tuples to
148148
/// efficiently de-structure their elements when appropriate.
149-
///
150-
/// @Comment {
151-
/// - Bug: The testing library should support variadic generics.
152-
/// ([103416861](rdar://103416861))
153-
/// }
149+
//
150+
// @Comment {
151+
// - Bug: The testing library should support variadic generics.
152+
// ([103416861](rdar://103416861))
153+
// }
154154
private init<E1, E2>(
155155
sequence: S,
156156
parameters: [Test.Parameter],
@@ -184,11 +184,11 @@ extension Test.Case {
184184
///
185185
/// This initializer overload is specialized for collections of 2-tuples to
186186
/// efficiently de-structure their elements when appropriate.
187-
///
188-
/// @Comment {
189-
/// - Bug: The testing library should support variadic generics.
190-
/// ([103416861](rdar://103416861))
191-
/// }
187+
//
188+
// @Comment {
189+
// - Bug: The testing library should support variadic generics.
190+
// ([103416861](rdar://103416861))
191+
// }
192192
init<E1, E2>(
193193
arguments collection: S,
194194
parameters: [Test.Parameter],

‎Sources/Testing/Running/Configuration.TestFilter.swift

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,7 @@ extension Configuration.TestFilter {
116116
/// of test IDs.
117117
///
118118
/// - Parameters:
119-
/// - selection: A set of test IDs to be excluded.
119+
/// - testIDs: A set of test IDs to be excluded.
120120
public init(excluding testIDs: some Collection<Test.ID>) {
121121
self.init(_kind: .testIDs(Set(testIDs), membership: .excluding))
122122
}

‎Sources/Testing/Running/Configuration.swift

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -69,8 +69,8 @@ public struct Configuration: Sendable {
6969
/// The conditions under which test iterations should continue.
7070
///
7171
/// If the value of this property is `nil`, a test plan will be run
72-
/// ``count`` times regardless of whether or not issues are encountered
73-
/// while running.
72+
/// ``maximumIterationCount`` times regardless of whether or not issues are
73+
/// encountered while running.
7474
public var continuationCondition: ContinuationCondition?
7575

7676
/// The maximum number of times the test run should iterate.
@@ -88,7 +88,8 @@ public struct Configuration: Sendable {
8888
/// - continuationCondition: The conditions under which test iterations
8989
/// should continue. If `nil`, the iterations should continue
9090
/// unconditionally `count` times.
91-
/// - count: The maximum number of times the test run should iterate.
91+
/// - maximumIterationCount: The maximum number of times the test run
92+
/// should iterate.
9293
public static func repeating(_ continuationCondition: ContinuationCondition? = nil, maximumIterationCount: Int) -> Self {
9394
Self(continuationCondition: continuationCondition, maximumIterationCount: maximumIterationCount)
9495
}

‎Sources/Testing/Running/Runner.Plan+Dumping.swift

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,6 @@ extension Runner.Plan {
9696
/// `true`, `Swift.dump(_:to:name:indent:maxDepth:maxItems:)` is called
9797
/// instead of the testing library's implementation.
9898
/// - indent: How many spaces to indent each level of text in the dump.
99-
/// - depth: How many levels deep `stepGraph` is in the total graph.
10099
///
101100
/// This function produces a detailed dump of the runner plan suitable for
102101
/// inclusion in diagnostics or for display as part of a command-line

‎Sources/Testing/Running/Runner.Plan.swift

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -445,7 +445,7 @@ extension Runner.Plan.Step {
445445
}
446446

447447
extension Runner.Plan.Action {
448-
/// A serializable snapshot of a ``Runner/Plan-swift.struct/Step/Action``
448+
/// A serializable snapshot of a ``Runner/Plan-swift.struct/Action``
449449
/// instance.
450450
@_spi(ForToolsIntegrationOnly)
451451
public enum Snapshot: Sendable, Codable {

0 commit comments

Comments
 (0)