Fix some issues with our DocC content.

We've built up some bit rot in our documentation. This PR resolves issues raised when building the DocC bundle.

Sources/Testing/Expectations/Expectation+Macro.swift

@@ -131,11 +131,10 @@
 /// discarded.
 ///
 /// Test functions can be annotated with `throws` and can throw errors which are
-/// then recorded as [issues](doc:Issues) when the test runs. If the intent is
-/// for a test to fail when an error is thrown by `expression`, rather than to
-/// explicitly check that an error is _not_ thrown by it, do not use this macro.
-/// Instead, simply call the code in question and allow it to throw an error
-/// naturally.
+/// then recorded as issues when the test runs. If the intent is for a test to
+/// fail when an error is thrown by `expression`, rather than to explicitly
+/// check that an error is _not_ thrown by it, do not use this macro. Instead,
+/// simply call the code in question and allow it to throw an error naturally.
 ///
 /// If the thrown error need only be an instance of a particular type, use
 /// ``expect(throws:_:sourceLocation:performing:)-79piu`` instead. If the thrown

Sources/Testing/Issues/KnownIssue.swift

@@ -110,7 +110,7 @@ public typealias KnownIssueMatcher = @Sendable (_ issue: Issue) -> Bool
 /// Because all errors thrown by `body` are caught as known issues, this
 /// function is not throwing. If only some errors or issues are known to occur
 /// while others should continue to cause test failures, use
-/// ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:when:matching:)-3n2cc``
+/// ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:when:matching:)-68e5g``
 /// instead.
 public func withKnownIssue(
   _ comment: Comment? = nil,
@@ -164,7 +164,7 @@ public func withKnownIssue(
 ///
 /// It is not necessary to specify both `precondition` and `issueMatcher` if
 /// only one is relevant. If all errors and issues should be considered known
-/// issues, use ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:)-4txq1``
+/// issues, use ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:)-5pxnd``
 /// instead.
 ///
 /// - Note: `issueMatcher` may be invoked more than once for the same issue.
@@ -225,7 +225,7 @@ public func withKnownIssue(
 /// Because all errors thrown by `body` are caught as known issues, this
 /// function is not throwing. If only some errors or issues are known to occur
 /// while others should continue to cause test failures, use
-/// ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:when:matching:)-5bsda``
+/// ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:when:matching:)-7azqg``
 /// instead.
 public func withKnownIssue(
   _ comment: Comment? = nil,
@@ -279,7 +279,7 @@ public func withKnownIssue(
 ///
 /// It is not necessary to specify both `precondition` and `issueMatcher` if
 /// only one is relevant. If all errors and issues should be considered known
-/// issues, use ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:)-8ibg4``
+/// issues, use ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:)-30kgk``
 /// instead.
 ///
 /// - Note: `issueMatcher` may be invoked more than once for the same issue.

Sources/Testing/Test.swift

@@ -124,8 +124,7 @@ public struct Test: Sendable {
   /// suites. They do not contain any test logic of their own, but they may
   /// have traits added to them that also apply to their subtests.
   ///
-  /// A test suite can be declared using the ``Suite(_:)`` or ``Suite(_:_:)``
-  /// macro.
+  /// A test suite can be declared using the ``Suite(_:_:)`` macro.
   public var isSuite: Bool {
     containingType != nil && testCases == nil
   }

Sources/Testing/Testing.docc/ExpectThrows.md

@@ -43,9 +43,9 @@ runtime not to mark the test as failing when those issues occur.
 
 ### Recording known issues in tests
 
-- ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:)-4txq1``
-- ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:)-8ibg4``
-- ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:when:matching:)-3n2cc``
-- ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:when:matching:)-5bsda``
+- ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:)-5pxnd``
+- ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:)-30kgk``
+- ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:when:matching:)-68e5g``
+- ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:when:matching:)-7azqg``
 - ``Issue``
 - ``KnownIssueMatcher``

Sources/Testing/Testing.docc/MigratingFromXCTest.md

@@ -502,8 +502,8 @@ to tell XCTest and its infrastructure that the issue should not cause the test
 to fail. The testing library has an equivalent function with synchronous and
 asynchronous variants:
 
-- ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:)-4txq1``
-- ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:)-8ibg4``
+- ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:)-5pxnd``
+- ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:)-30kgk``
 
 This function can be used to annotate a section of a test as having a known
 issue:
@@ -598,8 +598,8 @@ Additional options can be specified when calling `XCTExpectFailure()`:
 The testing library includes overloads of `withKnownIssue()` that take
 additional arguments with similar behavior:
 
-- ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:when:matching:)-3n2cc``
-- ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:when:matching:)-5bsda``
+- ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:when:matching:)-68e5g``
+- ``withKnownIssue(_:isIntermittent:fileID:filePath:line:column:_:when:matching:)-7azqg``
 
 To conditionally enable known-issue matching and/or to match only certain kinds
 of issues:

Sources/Testing/Testing.docc/OrganizingTests.md

@@ -145,8 +145,8 @@ The compiler will emit an error when presented with a test suite that does not
 meet this requirement.
 
 - Bug: Inherited availability is not always visible to the compiler during
-  expansion of the ``Suite(_:)`` and ``Suite(_:_:)`` macros. A test function may
-  crash when run on an unsupported system. ([110974351](rdar://110974351))
+  expansion of the ``Suite(_:_:)`` macro. A test function may crash when run on
+  an unsupported system. ([110974351](rdar://110974351))
 
 ### Classes must be final
 
@@ -166,5 +166,4 @@ class MenuItemTests { ... } // ❌ ERROR: this class is not final
 
 ## Topics
 
-- ``Suite(_:)``
 - ``Suite(_:_:)``