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

18 files changed

+117
-110
lines changed

Diff for: ‎Sources/Testing/Attachments/Attachment.swift

+5-5
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

Diff for: ‎Sources/Testing/Events/Event.swift

+5-2
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:

Diff for: ‎Sources/Testing/Events/Recorder/Event.HumanReadableOutputRecorder.swift

+3-3
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
}

Diff for: ‎Sources/Testing/ExitTests/ExitTest.swift

+2-2
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.

Diff for: ‎Sources/Testing/Issues/Issue.swift

+17-14
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:

Diff for: ‎Sources/Testing/Parameterization/Test.Case.Generator.swift

+15-15
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],

Diff for: ‎Sources/Testing/Running/Configuration.TestFilter.swift

+1-1
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
}

Diff for: ‎Sources/Testing/Running/Configuration.swift

+4-3
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
}

Diff for: ‎Sources/Testing/Running/Runner.Plan+Dumping.swift

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

Diff for: ‎Sources/Testing/Running/Runner.Plan.swift

+1-1
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 {

Diff for: ‎Sources/Testing/Support/CartesianProduct.swift

+10-10
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,11 @@
1717
/// `[(1, "a"), (1, "b"), (1, "c"), (2, "a"), (2, "b"), ... (3, "c")]`.
1818
///
1919
/// This type is not part of the public interface of the testing library.
20-
///
21-
/// @Comment {
22-
/// - Bug: The testing library should support variadic generics.
23-
/// ([103416861](rdar://103416861))
24-
/// }
20+
//
21+
// @Comment {
22+
// - Bug: The testing library should support variadic generics.
23+
// ([103416861](rdar://103416861))
24+
// }
2525
struct CartesianProduct<C1, C2>: LazySequenceProtocol where C1: Collection, C2: Collection {
2626
fileprivate var collection1: C1
2727
fileprivate var collection2: C2
@@ -63,11 +63,11 @@ extension CartesianProduct: Sendable where C1: Sendable, C2: Sendable {}
6363
/// while `collection2` is iterated `collection1.count` times.
6464
///
6565
/// For more information on Cartesian products, see ``CartesianProduct``.
66-
///
67-
/// @Comment {
68-
/// - Bug: The testing library should support variadic generics.
69-
/// ([103416861](rdar://103416861))
70-
/// }
66+
//
67+
// @Comment {
68+
// - Bug: The testing library should support variadic generics.
69+
// ([103416861](rdar://103416861))
70+
// }
7171
func cartesianProduct<C1, C2>(_ collection1: C1, _ collection2: C2) -> CartesianProduct<C1, C2> where C1: Collection, C2: Collection {
7272
CartesianProduct(collection1: collection1, collection2: collection2)
7373
}

Diff for: ‎Sources/Testing/Test+Macro.swift

+25-25
Original file line numberDiff line numberDiff line change
@@ -220,14 +220,14 @@ public macro Test<C>(
220220
/// During testing, the associated test function is called once for each element
221221
/// in `collection`.
222222
///
223-
/// @Comment {
224-
/// - Bug: The testing library should support variadic generics.
225-
/// ([103416861](rdar://103416861))
226-
/// }
227-
///
228223
/// ## See Also
229224
///
230225
/// - <doc:DefiningTests>
226+
//
227+
// @Comment {
228+
// - Bug: The testing library should support variadic generics.
229+
// ([103416861](rdar://103416861))
230+
// }
231231
@attached(peer) public macro Test<C>(
232232
_ displayName: _const String? = nil,
233233
_ traits: any TestTrait...,
@@ -273,14 +273,14 @@ extension Test {
273273
/// During testing, the associated test function is called once for each pair of
274274
/// elements in `collection1` and `collection2`.
275275
///
276-
/// @Comment {
277-
/// - Bug: The testing library should support variadic generics.
278-
/// ([103416861](rdar://103416861))
279-
/// }
280-
///
281276
/// ## See Also
282277
///
283278
/// - <doc:DefiningTests>
279+
//
280+
// @Comment {
281+
// - Bug: The testing library should support variadic generics.
282+
// ([103416861](rdar://103416861))
283+
// }
284284
@attached(peer)
285285
@_documentation(visibility: private)
286286
public macro Test<C1, C2>(
@@ -301,14 +301,14 @@ public macro Test<C1, C2>(
301301
/// During testing, the associated test function is called once for each pair of
302302
/// elements in `collection1` and `collection2`.
303303
///
304-
/// @Comment {
305-
/// - Bug: The testing library should support variadic generics.
306-
/// ([103416861](rdar://103416861))
307-
/// }
308-
///
309304
/// ## See Also
310305
///
311306
/// - <doc:DefiningTests>
307+
//
308+
// @Comment {
309+
// - Bug: The testing library should support variadic generics.
310+
// ([103416861](rdar://103416861))
311+
// }
312312
@attached(peer) public macro Test<C1, C2>(
313313
_ displayName: _const String? = nil,
314314
_ traits: any TestTrait...,
@@ -327,14 +327,14 @@ public macro Test<C1, C2>(
327327
/// During testing, the associated test function is called once for each element
328328
/// in `zippedCollections`.
329329
///
330-
/// @Comment {
331-
/// - Bug: The testing library should support variadic generics.
332-
/// ([103416861](rdar://103416861))
333-
/// }
334-
///
335330
/// ## See Also
336331
///
337332
/// - <doc:DefiningTests>
333+
//
334+
// @Comment {
335+
// - Bug: The testing library should support variadic generics.
336+
// ([103416861](rdar://103416861))
337+
// }
338338
@attached(peer)
339339
@_documentation(visibility: private)
340340
public macro Test<C1, C2>(
@@ -355,14 +355,14 @@ public macro Test<C1, C2>(
355355
/// During testing, the associated test function is called once for each element
356356
/// in `zippedCollections`.
357357
///
358-
/// @Comment {
359-
/// - Bug: The testing library should support variadic generics.
360-
/// ([103416861](rdar://103416861))
361-
/// }
362-
///
363358
/// ## See Also
364359
///
365360
/// - <doc:DefiningTests>
361+
//
362+
// @Comment {
363+
// - Bug: The testing library should support variadic generics.
364+
// ([103416861](rdar://103416861))
365+
// }
366366
@attached(peer) public macro Test<C1, C2>(
367367
_ displayName: _const String? = nil,
368368
_ traits: any TestTrait...,

Diff for: ‎Sources/Testing/Testing.docc/LimitingExecutionTime.md

+3-2
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,9 @@ resources to complete, may rely on downloaded data from a server, or may
1919
otherwise be dependent on external factors.
2020

2121
If a test may hang indefinitely or may consume too many system resources to
22-
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
23-
``Trait/timeLimit(_:)`` trait as an upper bound:
22+
complete effectively, consider setting a time limit for it so that it's marked
23+
as failing if it runs for an excessive amount of time. Use the
24+
``Trait/timeLimit(_:)-4kzjp`` trait as an upper bound:
2425

2526
```swift
2627
@Test(.timeLimit(.minutes(60))

Diff for: ‎Sources/Testing/Testing.docc/Traits.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ behavior of test functions.
3030
- ``Trait/disabled(_:sourceLocation:)``
3131
- ``Trait/disabled(if:_:sourceLocation:)``
3232
- ``Trait/disabled(_:sourceLocation:_:)``
33-
- ``Trait/timeLimit(_:)``
33+
- ``Trait/timeLimit(_:)-4kzjp``
3434

3535
### Running tests serially or in parallel
3636

Diff for: ‎Sources/Testing/Testing.docc/Traits/Trait.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
2222

2323
### Limiting the running time of tests
2424

25-
- ``Trait/timeLimit(_:)``
25+
- ``Trait/timeLimit(_:)-4kzjp``
2626

2727
### Running tests serially or in parallel
2828

0 commit comments

Comments
 (0)