Lower some symbols to SPI. (#548)

This PR lowers some API symbols to SPI, mostly as experimental
tools-only. These symbols are, we believe, important but deserve more
thought and design before we promote them to API.

As well, this PR merges the `comment` and `comments` properties of
`ConditionTrait` as redundant.

Resolves rdar://131937376.

### 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.

Sources/Testing/Issues/Issue.swift

@@ -215,6 +215,7 @@ extension Issue {
     public var sourceContext: SourceContext
 
     /// Whether or not this issue is known to occur.
+    @_spi(ForToolsIntegrationOnly)
     public var isKnown = false
 
     /// Initialize an issue instance with the specified details.

Sources/Testing/Parameterization/Test.Case.ID.swift

@@ -8,7 +8,6 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-@_spi(ForToolsIntegrationOnly)
 extension Test.Case: Identifiable {
   /// The ID of a test case.
   ///
@@ -21,8 +20,10 @@ extension Test.Case: Identifiable {
     ///
     /// The value of this property is `nil` if _any_ of the associated test
     /// case's arguments has a `nil` ID.
+    @_spi(ForToolsIntegrationOnly)
     public var argumentIDs: [Argument.ID]?
 
+    @_spi(ForToolsIntegrationOnly)
     public init(argumentIDs: [Argument.ID]?) {
       self.argumentIDs = argumentIDs
     }

Sources/Testing/Parameterization/Test.Case.swift

@@ -17,6 +17,7 @@ extension Test {
   public struct Case: Sendable {
     /// A type representing an argument passed to a parameter of a parameterized
     /// test function.
+    @_spi(Experimental) @_spi(ForToolsIntegrationOnly)
     public struct Argument: Sendable {
       /// A type representing the stable, unique identifier of a parameterized
       /// test argument.
@@ -71,6 +72,7 @@ extension Test {
     /// Non-parameterized test functions will have a single test case instance,
     /// and the value of this property will be an empty array for such test
     /// cases.
+    @_spi(Experimental) @_spi(ForToolsIntegrationOnly)
     public var arguments: [Argument]
 
     init(
@@ -117,6 +119,7 @@ extension Test {
   /// value that might be passed via this parameter to a test function. To
   /// obtain the arguments of a particular ``Test/Case`` paired with their
   /// corresponding parameters, use ``Test/Case/arguments``.
+  @_spi(Experimental) @_spi(ForToolsIntegrationOnly)
   public struct Parameter: Sendable {
     /// The zero-based index of this parameter within its associated test's
     /// parameter list.

Sources/Testing/Test.swift

@@ -178,6 +178,7 @@ public struct Test: Sendable {
   /// an array of values describing its parameters, which may be empty if the
   /// test function is non-parameterized. If this instance represents a test
   /// suite, the value of this property is `nil`.
+  @_spi(Experimental) @_spi(ForToolsIntegrationOnly)
   public var parameters: [Parameter]?
 
   /// Whether or not this instance is a test suite containing other tests.

Sources/Testing/Testing.docc/Documentation.md

@@ -59,7 +59,7 @@ their problems.
 - ``Test(_:_:arguments:_:)``
 - ``Test(_:_:arguments:)-3rzok``
 - ``CustomTestArgumentEncodable``
-- ``Test/Parameter``
+<!-- - ``Test/Parameter`` -->
 - ``Test/Case``
 
 ### Behavior validation

Sources/Testing/Traits/Comment.swift

@@ -144,6 +144,7 @@ extension Test {
   ///   - traitType: The type of ``Trait`` whose comments should be returned.
   ///
   /// - Returns: The comments found for the specified test trait type.
+  @_spi(Experimental)
   public func comments<T>(from traitType: T.Type) -> [Comment] where T: Trait {
     traits.lazy
       .compactMap { $0 as? T }

Sources/Testing/Traits/ConditionTrait+Macro.swift

@@ -61,8 +61,8 @@ extension Trait where Self == ConditionTrait {
   ) -> Self {
     // TODO: Semantic capture of platform name/version (rather than just a comment)
     Self(
-      comment: message ?? "Requires \(_description(ofPlatformName: platformName, version: version))",
       kind: .conditional(condition),
+      comments: [message ?? "Requires \(_description(ofPlatformName: platformName, version: version))"],
       sourceLocation: sourceLocation
     )
   }
@@ -93,8 +93,8 @@ extension Trait where Self == ConditionTrait {
   ) -> Self {
     // TODO: Semantic capture of platform name/version (rather than just a comment)
     Self(
-      comment: message ?? "Obsolete as of \(_description(ofPlatformName: platformName, version: version))",
       kind: .conditional(condition),
+      comments: [message ?? "Obsolete as of \(_description(ofPlatformName: platformName, version: version))"],
       sourceLocation: sourceLocation
     )
   }
@@ -112,8 +112,8 @@ extension Trait where Self == ConditionTrait {
   ///   call it directly.
   public static func __unavailable(message: Comment?, sourceLocation: SourceLocation) -> Self {
     Self(
-      comment: message ?? "Marked @available(*, unavailable)",
       kind: .unconditional(false),
+      comments: [message ?? "Marked @available(*, unavailable)"],
       sourceLocation: sourceLocation
     )
   }

Sources/Testing/Traits/ConditionTrait.swift

@@ -19,9 +19,6 @@
 /// - ``Trait/disabled(if:_:sourceLocation:)``
 /// - ``Trait/disabled(_:sourceLocation:_:)``
 public struct ConditionTrait: TestTrait, SuiteTrait {
-  /// An optional, user-specified comment describing this trait.
-  public var comment: Comment?
-
   /// An enumeration describing the kinds of conditions that can be represented
   /// by an instance of this type.
   enum Kind: Sendable {
@@ -68,6 +65,7 @@ public struct ConditionTrait: TestTrait, SuiteTrait {
   /// If this trait was created using a function such as
   /// ``enabled(if:_:sourceLocation:)`` that is evaluated at runtime, the value
   /// of this property is `false`.
+  @_spi(ForToolsIntegrationOnly)
   public var isConstant: Bool {
     switch kind {
     case .conditional:
@@ -77,6 +75,8 @@ public struct ConditionTrait: TestTrait, SuiteTrait {
     }
   }
 
+  public var comments: [Comment]
+
   /// The source location where this trait was specified.
   public var sourceLocation: SourceLocation
 
@@ -93,17 +93,13 @@ public struct ConditionTrait: TestTrait, SuiteTrait {
 
     if !result {
       let sourceContext = SourceContext(sourceLocation: sourceLocation)
-      throw SkipInfo(comment: commentOverride ?? comment, sourceContext: sourceContext)
+      throw SkipInfo(comment: commentOverride ?? comments.first, sourceContext: sourceContext)
     }
   }
 
   public var isRecursive: Bool {
     true
   }
-
-  public var comments: [Comment] {
-    Array(comment)
-  }
 }
 
 // MARK: -
@@ -132,7 +128,7 @@ extension Trait where Self == ConditionTrait {
     _ comment: Comment? = nil,
     sourceLocation: SourceLocation = #_sourceLocation
   ) -> Self {
-    Self(comment: comment, kind: .conditional(condition), sourceLocation: sourceLocation)
+    Self(kind: .conditional(condition), comments: Array(comment), sourceLocation: sourceLocation)
   }
 
   /// Construct a condition trait that causes a test to be disabled if it
@@ -152,7 +148,7 @@ extension Trait where Self == ConditionTrait {
     sourceLocation: SourceLocation = #_sourceLocation,
     _ condition: @escaping @Sendable () async throws -> Bool
   ) -> Self {
-    Self(comment: comment, kind: .conditional(condition), sourceLocation: sourceLocation)
+    Self(kind: .conditional(condition), comments: Array(comment), sourceLocation: sourceLocation)
   }
 
   /// Construct a condition trait that disables a test unconditionally.
@@ -167,7 +163,7 @@ extension Trait where Self == ConditionTrait {
     _ comment: Comment? = nil,
     sourceLocation: SourceLocation = #_sourceLocation
   ) -> Self {
-    Self(comment: comment, kind: .unconditional(false), sourceLocation: sourceLocation)
+    Self(kind: .unconditional(false), comments: Array(comment), sourceLocation: sourceLocation)
   }
 
   /// Construct a condition trait that causes a test to be disabled if it
@@ -193,7 +189,7 @@ extension Trait where Self == ConditionTrait {
     _ comment: Comment? = nil,
     sourceLocation: SourceLocation = #_sourceLocation
   ) -> Self {
-    Self(comment: comment, kind: .conditional { !(try condition()) }, sourceLocation: sourceLocation)
+    Self(kind: .conditional { !(try condition()) }, comments: Array(comment), sourceLocation: sourceLocation)
   }
 
   /// Construct a condition trait that causes a test to be disabled if it
@@ -213,6 +209,6 @@ extension Trait where Self == ConditionTrait {
     sourceLocation: SourceLocation = #_sourceLocation,
     _ condition: @escaping @Sendable () async throws -> Bool
   ) -> Self {
-    Self(comment: comment, kind: .conditional { !(try await condition()) }, sourceLocation: sourceLocation)
+    Self(kind: .conditional { !(try await condition()) }, comments: Array(comment), sourceLocation: sourceLocation)
   }
 }