Skip to content

Fix DocC warnings and errors, including those from SPI #836

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 10, 2024
Merged

Fix DocC warnings and errors, including those from SPI #836

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0f2e0b5
Fix DocC warnings and errors, including those from SPI
stmontgomery Nov 22, 2024
faa871d
Preserve @Comment wrapper
stmontgomery Dec 9, 2024
0a7343e
Whitespace
stmontgomery Dec 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions Sources/Testing/Attachments/Attachment.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 5 additions & 2 deletions Sources/Testing/Events/Event.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
6 changes: 3 additions & 3 deletions Sources/Testing/Events/Recorder/Event.HumanReadableOutputRecorder.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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() {}
}
}
Expand Down
4 changes: 2 additions & 2 deletions Sources/Testing/ExitTests/ExitTest.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
31 changes: 17 additions & 14 deletions Sources/Testing/Issues/Issue.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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:
Expand Down
30 changes: 15 additions & 15 deletions Sources/Testing/Parameterization/Test.Case.Generator.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
///
Expand Down Expand Up @@ -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],
Expand Down Expand Up @@ -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],
Expand Down
2 changes: 1 addition & 1 deletion Sources/Testing/Running/Configuration.TestFilter.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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))
}
Expand Down
7 changes: 4 additions & 3 deletions Sources/Testing/Running/Configuration.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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)
}
Expand Down
1 change: 0 additions & 1 deletion Sources/Testing/Running/Runner.Plan+Dumping.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion Sources/Testing/Running/Runner.Plan.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
20 changes: 10 additions & 10 deletions Sources/Testing/Support/CartesianProduct.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
}
50 changes: 25 additions & 25 deletions Sources/Testing/Test+Macro.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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...,
Expand Down Expand Up @@ -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>(
Expand All @@ -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...,
Expand All @@ -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>(
Expand All @@ -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...,
Expand Down
5 changes: 3 additions & 2 deletions Sources/Testing/Testing.docc/LimitingExecutionTime.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
2 changes: 1 addition & 1 deletion Sources/Testing/Testing.docc/Traits.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion Sources/Testing/Testing.docc/Traits/Trait.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading