Updates to conform documentation to API collection style guidelines (#343)

medreisbach · chuckdude · grynspan · web-flow · commit b46b3f3277e3 · 2024-04-22T15:44:23.000-07:00
Updates to conform to API collection style guidelines: - Begin titles with a noun. - Place everything under topic groups. - Begin topic group headings with a gerund. - Add symbols alongside articles in the topic groups. Curation changes: - Move expected throws content up into expectations and split known issues into its own collection. Part 2 of changes for rdar://119702877 ### 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. --------- Co-authored-by: Chuck Toporek <76215+chuckdude@users.noreply.github.com> Co-authored-by: Jonathan Grynspan <jgrynspan@apple.com>
diff --git a/Sources/Testing/Testing.docc/Documentation.md b/Sources/Testing/Testing.docc/Documentation.md
@@ -5,7 +5,7 @@
 <!--
 This source file is part of the Swift.org open source project
 
-Copyright (c) 2023 Apple Inc. and the Swift project authors
+Copyright (c) 2023–2024 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
@@ -60,6 +60,7 @@ concurrency, and parameterize test functions across wide ranges of inputs.
 ### Behavior validation
 
 - <doc:Expectations>
+- <doc:known-issues>
 
 ### Test customization
 
diff --git a/Sources/Testing/Testing.docc/ExpectThrows.md b/Sources/Testing/Testing.docc/ExpectThrows.md
diff --git a/Sources/Testing/Testing.docc/Expectations.md b/Sources/Testing/Testing.docc/Expectations.md
@@ -1,9 +1,9 @@
-# Validating behavior using expectations
+# Expectations and confirmations
 
 <!--
 This source file is part of the Swift.org open source project
 
-Copyright (c) 2023 Apple Inc. and the Swift project authors
+Copyright (c) 2023–2024 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
@@ -14,25 +14,35 @@ Check for expected values and outcomes in tests.
 
 ## Overview
 
-Tests may validate behaviors using expectations. This page describes the various
-built-in expectation APIs.
+The testing library provides `#expect()` and `#require()` macros you use to 
+validate expected outcomes. To validate that an error is thrown, or _not_ thrown, 
+the testing library provides several overloads of the macros that you can use.
+Use a ``Confirmation`` to confirm the occurrence of an asynchronous event that
+you can't check directly using an expectation.
 
 ## Topics
 
-### Validating behavior using expectations
+### Checking expectations
 
 - ``expect(_:_:sourceLocation:)``
 - ``require(_:_:sourceLocation:)-5l63q``
 - ``require(_:_:sourceLocation:)-6w9oo``
 
-### Validating asynchronous behavior using confirmations
+### Checking that errors are thrown
 
-- ``Confirmation``
-- ``confirmation(_:expectedCount:fileID:filePath:line:column:_:)``
+- ``expect(throws:_:sourceLocation:performing:)-79piu``
+- ``expect(throws:_:sourceLocation:performing:)-1xr34``
+- ``expect(_:sourceLocation:performing:throws:)``
+- ``expect(throws:_:sourceLocation:performing:)-5lzjz``
+- ``require(throws:_:sourceLocation:performing:)-76bjn``
+- ``require(throws:_:sourceLocation:performing:)-7v83e``
+- ``require(_:sourceLocation:performing:throws:)``
+- ``require(throws:_:sourceLocation:performing:)-36uzc``
 
-### Validating errors and issues in tests
+### Confirming that asynchronous events occur
 
-- <doc:ExpectThrows>
+- ``confirmation(_:expectedCount:fileID:filePath:line:column:_:)``
+- ``Confirmation``
 
 ### Retrieving information about checked expectations
 
diff --git a/Sources/Testing/Testing.docc/Traits.md b/Sources/Testing/Testing.docc/Traits.md
@@ -1,9 +1,9 @@
-# Adding traits to tests
+# Traits
 
 <!--
 This source file is part of the Swift.org open source project
 
-Copyright (c) 2023 Apple Inc. and the Swift project authors
+Copyright (c) 2023–2024 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
@@ -14,24 +14,52 @@ Add traits to tests to annotate them or customize their behavior.
 
 ## Overview
 
-This article describes the ``Trait``, ``TestTrait``, and ``SuiteTrait``
-protocols, lists the traits provided by the testing library, and lists functions
-that can be used to create them.
-
-The ``Trait``, ``TestTrait``, and ``SuiteTrait`` protocols are used to define
-types that customize the behavior of test functions and test suites.
+Pass built-in traits to test functions or suite types to comment, categorize, 
+classify, and modify runtime behaviors. You can also use the ``Trait``, ``TestTrait``, 
+and ``SuiteTrait`` protocols to create your own types that customize the 
+behavior of test functions.
 
 ## Topics
 
+### Customizing runtime behaviors
+
 - <doc:EnablingAndDisabling>
+- <doc:LimitingExecutionTime>
+- <doc:Parallelization>
+- ``Trait/enabled(if:_:fileID:filePath:line:column:)``
+- ``Trait/enabled(_:fileID:filePath:line:column:_:)``
+- ``Trait/disabled(_:fileID:filePath:line:column:)``
+- ``Trait/disabled(if:_:fileID:filePath:line:column:)``
+- ``Trait/disabled(_:fileID:filePath:line:column:_:)``
+- ``Trait/timeLimit(_:)``
+
+<!--
+HIDDEN: .serial is experimental SPI pending feature review.
+### Running tests serially or in parallel
+- ``SerialTrait``
+ -->
+
+### Annotating tests
+
 - <doc:AddingTags>
 - <doc:AddingComments>
 - <doc:AssociatingBugs>
-- <doc:LimitingExecutionTime>
-- <doc:Parallelization>
+- <doc:BugIdentifiers>
+- ``Tag()``
+- ``Trait/bug(_:relationship:_:)-86mmm``
+- ``Trait/bug(_:relationship:_:)-3hsi5``
 
-### Creating a custom trait
+### Creating custom traits
 
 - ``Trait``
 - ``TestTrait``
 - ``SuiteTrait``
+
+### Supporting types
+
+- ``Bug``
+- ``Comment``
+- ``ConditionTrait``
+- ``Tag``
+- ``Tag/List``
+- ``TimeLimitTrait``
diff --git a/Sources/Testing/Testing.docc/Traits/Trait.md b/Sources/Testing/Testing.docc/Traits/Trait.md
@@ -1,5 +1,15 @@
 # ``Trait``
 
+<!--
+This source file is part of the Swift.org open source project
+
+Copyright (c) 2024 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
+-->
+
 ## Topics
 
 ### Enabling and disabling tests
diff --git a/Sources/Testing/Testing.docc/known-issues.md b/Sources/Testing/Testing.docc/known-issues.md
@@ -0,0 +1,33 @@
+# Known issues
+
+<!--
+This source file is part of the Swift.org open source project
+
+Copyright © 2023–2024 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
+-->
+
+Highlight known issues when running tests.
+
+## Overview
+
+The testing library provides a function, `withKnownIssue()`, that you
+use to mark issues as known. Use this function to inform the testing library 
+at runtime not to mark the test as failing when issues occur.
+
+## Topics
+
+### Recording known issues in tests
+
+- ``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``
+- ``KnownIssueMatcher``
+
+### Describing a failure or warning
+
+- ``Issue``
