88// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
99//
1010
11- /// A type that defines a condition which must be satisfied for a test to be
12- /// enabled .
11+ /// A type that defines a condition which must be satisfied for the testing
12+ /// library to enable a test .
1313///
1414/// To add this trait to a test, use one of the following functions:
1515///
1919/// - ``Trait/disabled(if:_:sourceLocation:)``
2020/// - ``Trait/disabled(_:sourceLocation:_:)``
2121public struct ConditionTrait : TestTrait , SuiteTrait {
22- /// An enumeration describing the kinds of conditions that can be represented
23- /// by an instance of this type .
22+ /// An enumeration that describes the conditions that an instance of this type
23+ /// can represent .
2424 enum Kind : Sendable {
25- /// The trait is conditional on the result of calling a function.
25+ /// Enabling the test is conditional on the result of calling a function.
2626 ///
2727 /// - Parameters:
2828 /// - body: The function to call. The result of this function determines
@@ -39,7 +39,8 @@ public struct ConditionTrait: TestTrait, SuiteTrait {
3939 /// - body: The function to call. The result of this function determines
4040 /// whether or not the condition was met.
4141 ///
42- /// - Returns: An instance of this type.
42+ /// - Returns: A trait that marks a test's enabled status as the result of
43+ /// calling a function.
4344 static func conditional( _ body: @escaping @Sendable ( ) async throws -> Bool ) -> Self {
4445 conditional { ( ) -> ( Bool , comment: Comment ? ) in
4546 return ( try await body ( ) , nil )
@@ -49,14 +50,14 @@ public struct ConditionTrait: TestTrait, SuiteTrait {
4950 /// The trait is unconditional and always has the same result.
5051 ///
5152 /// - Parameters:
52- /// - value: Whether or not the condition was met .
53+ /// - value: Whether or not the test is enabled .
5354 case unconditional( _ value: Bool )
5455 }
5556
56- /// The kind of condition represented by this instance .
57+ /// The kind of condition represented by this trait .
5758 var kind : Kind
5859
59- /// Whether or not this trait has a condition that is evaluated at runtime.
60+ /// Whether this trait's condition is constant, or evaluated at runtime.
6061 ///
6162 /// If this trait was created using a function such as
6263 /// ``disabled(_:sourceLocation:)`` that unconditionally enables or disables a
@@ -77,7 +78,7 @@ public struct ConditionTrait: TestTrait, SuiteTrait {
7778
7879 public var comments : [ Comment ]
7980
80- /// The source location where this trait was specified.
81+ /// The source location where this trait is specified.
8182 public var sourceLocation : SourceLocation
8283
8384 public func prepare( for test: Test ) async throws {
@@ -110,24 +111,23 @@ public struct ConditionTrait: TestTrait, SuiteTrait {
110111// MARK: -
111112
112113extension Trait where Self == ConditionTrait {
113- /// Construct a condition trait that causes a test to be disabled if it
114- /// returns `false`.
114+ /// Constructs a condition trait that disables a test if it returns `false`.
115115 ///
116116 /// - Parameters:
117- /// - condition: A closure containing the trait's custom condition logic. If
118- /// this closure returns `true`, the test is allowed to run. Otherwise,
119- /// the test is skipped .
120- /// - comment: An optional, user-specified comment describing this trait.
117+ /// - condition: A closure that contains the trait's custom condition logic.
118+ /// If this closure returns `true`, the trait allows the test to run.
119+ /// Otherwise, the testing library skips the test .
120+ /// - comment: An optional comment that describes this trait.
121121 /// - sourceLocation: The source location of the trait.
122122 ///
123- /// - Returns: An instance of ``ConditionTrait`` that will evaluate the
124- /// specified closure.
125- ///
126- /// @Comment {
127- /// - Bug: `condition` cannot be `async` without making this function
128- /// `async` even though `condition` is not evaluated locally.
129- /// ([103037177](rdar://103037177))
130- /// }
123+ /// - Returns: An instance of ``ConditionTrait`` that evaluates the
124+ /// closure you provide .
125+ //
126+ // @Comment {
127+ // - Bug: `condition` cannot be `async` without making this function
128+ // `async` even though `condition` is not evaluated locally.
129+ // ([103037177](rdar://103037177))
130+ // }
131131 public static func enabled(
132132 if condition: @autoclosure @escaping @Sendable ( ) throws -> Bool ,
133133 _ comment: Comment ? = nil ,
@@ -136,18 +136,17 @@ extension Trait where Self == ConditionTrait {
136136 Self ( kind: . conditional( condition) , comments: Array ( comment) , sourceLocation: sourceLocation)
137137 }
138138
139- /// Construct a condition trait that causes a test to be disabled if it
140- /// returns `false`.
139+ /// Constructs a condition trait that disables a test if it returns `false`.
141140 ///
142141 /// - Parameters:
143- /// - comment: An optional, user-specified comment describing this trait.
142+ /// - comment: An optional comment that describes this trait.
144143 /// - sourceLocation: The source location of the trait.
145- /// - condition: A closure containing the trait's custom condition logic. If
146- /// this closure returns `true`, the test is allowed to run. Otherwise,
147- /// the test is skipped .
144+ /// - condition: A closure that contains the trait's custom condition logic.
145+ /// If this closure returns `true`, the trait allows the test to run.
146+ /// Otherwise, the testing library skips the test .
148147 ///
149- /// - Returns: An instance of ``ConditionTrait`` that will evaluate the
150- /// specified closure.
148+ /// - Returns: An instance of ``ConditionTrait`` that evaluates the
149+ /// closure you provide .
151150 public static func enabled(
152151 _ comment: Comment ? = nil ,
153152 sourceLocation: SourceLocation = #_sourceLocation,
@@ -156,13 +155,13 @@ extension Trait where Self == ConditionTrait {
156155 Self ( kind: . conditional( condition) , comments: Array ( comment) , sourceLocation: sourceLocation)
157156 }
158157
159- /// Construct a condition trait that disables a test unconditionally.
158+ /// Constructs a condition trait that disables a test unconditionally.
160159 ///
161160 /// - Parameters:
162- /// - comment: An optional, user-specified comment describing this trait.
161+ /// - comment: An optional comment that describes this trait.
163162 /// - sourceLocation: The source location of the trait.
164163 ///
165- /// - Returns: An instance of ``ConditionTrait`` that will always disable the
164+ /// - Returns: An instance of ``ConditionTrait`` that always disables the
166165 /// test to which it is added.
167166 public static func disabled(
168167 _ comment: Comment ? = nil ,
@@ -171,24 +170,23 @@ extension Trait where Self == ConditionTrait {
171170 Self ( kind: . unconditional( false ) , comments: Array ( comment) , sourceLocation: sourceLocation)
172171 }
173172
174- /// Construct a condition trait that causes a test to be disabled if it
175- /// returns `true`.
173+ /// Constructs a condition trait that disables a test if its value is true.
176174 ///
177175 /// - Parameters:
178- /// - condition: A closure containing the trait's custom condition logic. If
179- /// this closure returns `false`, the test is allowed to run. Otherwise,
180- /// the test is skipped .
181- /// - comment: An optional, user-specified comment describing this trait.
176+ /// - condition: A closure that contains the trait's custom condition logic.
177+ /// If this closure returns `false`, the trait allows the test to run.
178+ /// Otherwise, the testing library skips the test .
179+ /// - comment: An optional comment that describes this trait.
182180 /// - sourceLocation: The source location of the trait.
183181 ///
184- /// - Returns: An instance of ``ConditionTrait`` that will evaluate the
185- /// specified closure.
186- ///
187- /// @Comment {
188- /// - Bug: `condition` cannot be `async` without making this function
189- /// `async` even though `condition` is not evaluated locally.
190- /// ([103037177](rdar://103037177))
191- /// }
182+ /// - Returns: An instance of ``ConditionTrait`` that evaluates the
183+ /// closure you provide .
184+ //
185+ // @Comment {
186+ // - Bug: `condition` cannot be `async` without making this function
187+ // `async` even though `condition` is not evaluated locally.
188+ // ([103037177](rdar://103037177))
189+ // }
192190 public static func disabled(
193191 if condition: @autoclosure @escaping @Sendable ( ) throws -> Bool ,
194192 _ comment: Comment ? = nil ,
@@ -197,17 +195,16 @@ extension Trait where Self == ConditionTrait {
197195 Self ( kind: . conditional { !( try condition ( ) ) } , comments: Array ( comment) , sourceLocation: sourceLocation)
198196 }
199197
200- /// Construct a condition trait that causes a test to be disabled if it
201- /// returns `true`.
198+ /// Constructs a condition trait that disables a test if its value is true.
202199 ///
203200 /// - Parameters:
204- /// - comment: An optional, user-specified comment describing this trait.
201+ /// - comment: An optional comment that describes this trait.
205202 /// - sourceLocation: The source location of the trait.
206- /// - condition: A closure containing the trait's custom condition logic. If
207- /// this closure returns `false`, the test is allowed to run. Otherwise,
208- /// the test is skipped .
203+ /// - condition: A closure that contains the trait's custom condition logic.
204+ /// If this closure returns `false`, the trait allows the test to run.
205+ /// Otherwise, the testing library skips the test .
209206 ///
210- /// - Returns: An instance of ``ConditionTrait`` that will evaluate the
207+ /// - Returns: An instance of ``ConditionTrait`` that evaluates the
211208 /// specified closure.
212209 public static func disabled(
213210 _ comment: Comment ? = nil ,
0 commit comments