Deprecate double-closure variants of #expect/#require

Author: grynspan

Diff for: Sources/Testing/Expectations/Expectation+Macro.swift

@@ -375,6 +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.")
 @discardableResult
 @freestanding(expression) public macro expect<R>(
   _ comment: @autoclosure () -> Comment? = nil,
@@ -426,6 +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.")
 @discardableResult
 @freestanding(expression) public macro require<R>(
   _ comment: @autoclosure () -> Comment? = nil,

Diff for: Sources/Testing/Testing.docc/AvailabilityStubs/ExpectComplexThrows.md

@@ -0,0 +1,28 @@
+# ``expect(_:sourceLocation:performing:throws:)``
+
+<!--
+This source file is part of the Swift.org open source project
+
+Copyright (c) 2023 Apple Inc. and the Swift project authors
+Licensed under Apache License v2.0 with Runtime Library Exception
+
+See https://swift.org/LICENSE.txt for license information
+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)
+}
+
+@DeprecationSummary {
+  Examine the result of ``expect(throws:_:sourceLocation:performing:)-7du1h`` or
+  ``expect(throws:_:sourceLocation:performing:)-1hfms`` instead:
+  
+  ```swift
+  let error = #expect(throws: FoodTruckError.self) {
+    ...
+  }
+  #expect(error?.napkinCount == 0)
+  ```
+}

Diff for: Sources/Testing/Testing.docc/AvailabilityStubs/RequireComplexThrows.md

@@ -0,0 +1,28 @@
+# ``require(_:sourceLocation:performing:throws:)``
+
+<!--
+This source file is part of the Swift.org open source project
+
+Copyright (c) 2023 Apple Inc. and the Swift project authors
+Licensed under Apache License v2.0 with Runtime Library Exception
+
+See https://swift.org/LICENSE.txt for license information
+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)
+}
+
+@DeprecationSummary {
+  Examine the result of ``require(throws:_:sourceLocation:performing:)-7n34r``
+  or ``require(throws:_:sourceLocation:performing:)-4djuw`` instead:
+  
+  ```swift
+  let error = try #require(throws: FoodTruckError.self) {
+    ...
+  }
+  #expect(error.napkinCount == 0)
+  ```
+}