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

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

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.

Author: grynspan

Diff for: 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,

Diff for: 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,

Diff for: 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:
 

Diff for: 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:
 

Diff for: 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() {

Diff for: 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")