Mark #expect(_:throws:) and #require(_:throws:) as to-be-deprecated. (#875)

These symbols should go through a transition period where they are
documented as to-be-deprecated rather than being deprecated outright. My
mistake.

With this change applied, Xcode treats these macros as deprecated
(deemphasizing them in autocomplete, for instance) and DocC marks them
as deprecated in an unspecified Swift version, but no warning is emitted
if they are used. This is consistent with API marked
`API_TO_BE_DEPRECATED` or `deprecated: 100000.0` in Apple's SDKs.

> [!NOTE]
> There is a bug in the DocC compiler that emits a diagnostic of the
form:
>
> > ⚠️ 'require(_:sourceLocation:performing:throws:)' isn't
unconditionally deprecated
>
> This issue is being tracked already with rdar://141785948.

Resolves #873.

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

Author: grynspan

Documentation/Proposals/0006-return-errors-from-expect-throws.md

@@ -105,7 +105,7 @@ is not statically available. The problematic overloads will also be deprecated:
 -) where E: Error & Equatable
 +) -> E where E: Error & Equatable
 
-+@available(*, deprecated, message: "Examine the result of '#expect(throws:)' instead.")
++@available(swift, introduced: 6.0, deprecated: 100000.0, message: "Examine the result of '#expect(throws:)' instead.")
 +@discardableResult
  @freestanding(expression) public macro expect<R>(
    _ comment: @autoclosure () -> Comment? = nil,
@@ -115,7 +115,7 @@ is not statically available. The problematic overloads will also be deprecated:
 -)
 +) -> (any Error)?
 
-+@available(*, deprecated, message: "Examine the result of '#require(throws:)' instead.")
++@available(swift, introduced: 6.0, deprecated: 100000.0, message: "Examine the result of '#require(throws:)' instead.")
 +@discardableResult
  @freestanding(expression) public macro require<R>(
    _ comment: @autoclosure () -> Comment? = nil,

Sources/Testing/Expectations/Expectation+Macro.swift

@@ -375,7 +375,7 @@ public macro require<R>(
 /// ``expect(throws:_:sourceLocation:performing:)-1hfms`` instead. If the thrown
 /// error need only equal another instance of [`Error`](https://developer.apple.com/documentation/swift/error),
 /// use ``expect(throws:_:sourceLocation:performing:)-7du1h`` instead.
-@available(*, deprecated, message: "Examine the result of '#expect(throws:)' instead.")
+@available(swift, introduced: 6.0, deprecated: 100000.0, message: "Examine the result of '#expect(throws:)' instead.")
 @discardableResult
 @freestanding(expression) public macro expect<R>(
   _ comment: @autoclosure () -> Comment? = nil,
@@ -427,7 +427,7 @@ public macro require<R>(
 ///
 /// If `expression` should _never_ throw, simply invoke the code without using
 /// this macro. The test will then fail if an error is thrown.
-@available(*, deprecated, message: "Examine the result of '#require(throws:)' instead.")
+@available(swift, introduced: 6.0, deprecated: 100000.0, message: "Examine the result of '#require(throws:)' instead.")
 @discardableResult
 @freestanding(expression) public macro require<R>(
   _ comment: @autoclosure () -> Comment? = nil,

Sources/Testing/Testing.docc/AvailabilityStubs/ExpectComplexThrows.md

@@ -11,11 +11,11 @@ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 -->
 
 @Metadata {
-  @Available(Swift, introduced: 6.0, deprecated: 999.0)
-  @Available(Xcode, introduced: 16.0, deprecated: 999.0)
+  @Available(Swift, introduced: 6.0)
+  @Available(Xcode, introduced: 16.0)
 }
 
-@DeprecationSummary {
+@DeprecationSummary { <!-- Warning when compiling DocC: rdar://141785948 -->
   Examine the result of ``expect(throws:_:sourceLocation:performing:)-7du1h`` or
   ``expect(throws:_:sourceLocation:performing:)-1hfms`` instead:
 

Sources/Testing/Testing.docc/AvailabilityStubs/RequireComplexThrows.md

@@ -11,11 +11,11 @@ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 -->
 
 @Metadata {
-  @Available(Swift, introduced: 6.0, deprecated: 999.0)
-  @Available(Xcode, introduced: 16.0, deprecated: 999.0)
+  @Available(Swift, introduced: 6.0)
+  @Available(Xcode, introduced: 16.0)
 }
 
-@DeprecationSummary {
+@DeprecationSummary { <!-- Warning when compiling DocC: rdar://141785948 -->
   Examine the result of ``require(throws:_:sourceLocation:performing:)-7n34r``
   or ``require(throws:_:sourceLocation:performing:)-4djuw`` instead:
 

Sources/Testing/Testing.docc/testing-for-errors-in-swift-code.md

@@ -48,8 +48,8 @@ running your test if the code doesn't throw the expected error.
 
 To check that the code under test throws an error of any type, pass
 `(any Error).self` as the first argument to either
-``expect(throws:_:sourceLocation:performing:)-1xr34`` or
-``require(_:_:sourceLocation:)-5l63q``:
+``expect(throws:_:sourceLocation:performing:)-1hfms`` or
+``require(throws:_:sourceLocation:performing:)-7n34r``:
 
 ```swift
 @Test func cannotAddToppingToPizzaBeforeStartOfList() {

Tests/TestingTests/IssueTests.swift

@@ -491,7 +491,6 @@ final class IssueTests: XCTestCase {
     }.run(configuration: .init())
   }
 
-  @available(*, deprecated)
   func testErrorCheckingWithExpect() async throws {
     let expectationFailed = expectation(description: "Expectation failed")
     expectationFailed.isInverted = true
@@ -540,7 +539,6 @@ final class IssueTests: XCTestCase {
     await fulfillment(of: [expectationFailed], timeout: 0.0)
   }
 
-  @available(*, deprecated)
   func testErrorCheckingWithExpect_Mismatching() async throws {
     let expectationFailed = expectation(description: "Expectation failed")
     expectationFailed.expectedFulfillmentCount = 13
@@ -665,7 +663,6 @@ final class IssueTests: XCTestCase {
     await fulfillment(of: [expectationFailed], timeout: 0.0)
   }
 
-  @available(*, deprecated)
   func testErrorCheckingWithExpectAsync() async throws {
     let expectationFailed = expectation(description: "Expectation failed")
     expectationFailed.isInverted = true
@@ -709,7 +706,6 @@ final class IssueTests: XCTestCase {
     await fulfillment(of: [expectationFailed], timeout: 0.0)
   }
 
-  @available(*, deprecated)
   func testErrorCheckingWithExpectAsync_Mismatching() async throws {
     let expectationFailed = expectation(description: "Expectation failed")
     expectationFailed.expectedFulfillmentCount = 13
@@ -826,7 +822,6 @@ final class IssueTests: XCTestCase {
     await fulfillment(of: [expectationFailed], timeout: 0.0)
   }
 
-  @available(*, deprecated)
   func testErrorCheckingWithExpect_ThrowingFromErrorMatcher() async throws {
     let errorCaught = expectation(description: "Error matcher's error caught")
     let expectationFailed = expectation(description: "Expectation failed")
@@ -854,7 +849,6 @@ final class IssueTests: XCTestCase {
     await fulfillment(of: [errorCaught, expectationFailed], timeout: 0.0)
   }
 
-  @available(*, deprecated)
   func testErrorCheckingWithExpectAsync_ThrowingFromErrorMatcher() async throws {
     let errorCaught = expectation(description: "Error matcher's error caught")
     let expectationFailed = expectation(description: "Expectation failed")
@@ -882,7 +876,6 @@ final class IssueTests: XCTestCase {
     await fulfillment(of: [errorCaught, expectationFailed], timeout: 0.0)
   }
 
-  @available(*, deprecated)
   func testErrorCheckingWithRequire_ThrowingFromErrorMatcher() async throws {
     let errorCaught = expectation(description: "Error matcher's error caught")
     let expectationFailed = expectation(description: "Expectation failed")
@@ -911,7 +904,6 @@ final class IssueTests: XCTestCase {
     await fulfillment(of: [errorCaught, expectationFailed], timeout: 0.0)
   }
 
-  @available(*, deprecated)
   func testErrorCheckingWithRequireAsync_ThrowingFromErrorMatcher() async throws {
     let errorCaught = expectation(description: "Error matcher's error caught")
     let expectationFailed = expectation(description: "Expectation failed")