[SWT-NNNN] Return the thrown error from #expect(throws:) and #require(throws:).

[grynspan]

This PR changes the signatures of the various throws: overloads of #expect and #require so that on success they return the error that was thrown rather than Void. This then allows more ergonomic inspection of the error's properties:

let error = try #require(throws: MyError.self) {
  try f()
}
#expect(error.hasWidget)
#expect(error.userName == "John Smith")

For more information, see the proposal document.

Resolves rdar://138235250.

Further PR Details

It is not possible to overload a macro or function solely by return type without the compiler reporting `Ambiguous use of 'f()'`, so we are not able to stage this change in using `@_spi(Experimental)` without breaking test code that already imports our SPI.

This change is potentially source-breaking for tests that inadvertently forward the result of these macro invocations to an enclosing scope. For example, the compiler will start emitting a warning here:

func bar(_ pfoo: UnsafePointer<Foo>) throws { ... }

withUnsafePointer(to: foo) { pfoo in // ⚠️ Result of call to 'withUnsafePointer(to:_:)' is unused
  #expect(throws: BadFooError.self) {
    try bar(pfoo)
  }
}

This warning can be suppressed by assigning the result of #expect (or of withUnsafePointer(to:_:)) to _:

func bar(_ pfoo: UnsafePointer<Foo>) throws { ... }

withUnsafePointer(to: foo) { pfoo in
  _ = #expect(throws: BadFooError.self) {
    try bar(pfoo)
  }
}

Because #expect and #require are macros, they cannot be referenced by name like functions, so you cannot assign them to variables (and then run into trouble with the types of those variables.)

Finally, this change deprecates the variants of #expect and #require that take two closures:

#expect { // ⚠️ 'expect(_:sourceLocation:performing:throws:)' is deprecated: Examine the result of '#expect(throws:)' instead.
  ...
} throws: { error in
  guard let error = error as? FoodTruckError else {
    return false
  }
  return error.napkinCount == 0
}

These variants are no longer needed because you can simply examine the result of the other variants:

let error = #expect(throws: FoodTruckError.self) {
  ...
}
#expect(error?.napkinCount == 0)

Checklist:

• Code and documentation should follow the style of the Style Guide.
• If public symbols are renamed or modified, DocC references should be updated.

[grynspan]

@swift-ci test

[grynspan]

@swift-ci test

[grynspan]

@swift-ci test

[grynspan]

@swift-ci test

[grynspan]

@swift-ci test

[dabrahams]

Nice!

[grynspan]

@swift-ci test

[grynspan]

@swift-ci test

[grynspan]

@swift-ci test Linux

[grynspan]

@swift-ci test