Updates to articles to conform to some documentation style. (#344)

Updates to articles to conform to some style guidelines:
    - Begin an article title with a gerund
    - Start section headings with an imperative verb.
- Remove some symbols references that already exist alongside these
articles in collection topic groups.

Part 3 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 <[email protected]>

Author: medreisbach

Sources/Testing/Testing.docc/AddingComments.md

@@ -28,7 +28,7 @@ Seeing comments related to tests in these contexts can help diagnose issues more
 quickly. Comments can be added to test declarations and the testing library will
 automatically capture and show them when issues are recorded.
 
-## Adding a code comment to a test
+## Add a code comment to a test
 
 To include a comment on a test or suite, write an ordinary Swift code comment
 immediately before its `@Test` or `@Suite` attribute:
@@ -67,7 +67,7 @@ includes an example code snippet or diagram.
 <!-- FIXME: Uncomment this section if/when the `.comment(...)` trait is promoted
   to non-experimental SPI
 
-## Adding a comment to a test programmatically
+## Add a comment programmatically
 
 For more precise control over a comment's content, comments can be added to a
 test programmatically by explicitly specifying them as trait arguments to the
@@ -86,7 +86,7 @@ func lunchMenu() {
 }
 ``` -->
 
-## Using test comments effectively
+## Use test comments effectively
 
 As in normal code, comments on tests are generally most useful when:
 
@@ -95,11 +95,3 @@ As in normal code, comments on tests are generally most useful when:
 
 If a test is related to a bug or issue, consider using the ``Bug`` trait instead
 of comments. For more information, review <doc:AssociatingBugs>.
-
-
-## Topics
-
-- ``Comment``
-<!-- FIXME: Uncomment this section if/when the `.comment(...)` trait is promoted
-  to non-experimental SPI.
-- ``Trait/comment(_:)`` -->

Sources/Testing/Testing.docc/AddingTags.md

@@ -10,7 +10,7 @@ See https://swift.org/LICENSE.txt for license information
 See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 -->
 
-Add tags to tests and customize their appearance.
+Use tags to provide semantic information for organization, filtering, and customizing appearances.
 
 ## Overview
 
@@ -24,7 +24,7 @@ functions at the source level, while tags provide semantic information for a
 test that can be shared with any number of other tests across test suites,
 source files, and even test targets.
 
-## Adding tags
+## Add a tag
 
 To add a tag to a test, use the ``Trait/tags(_:)-505n9`` trait. This trait takes
 a sequence of tags as its argument, and those tags are then applied to the
@@ -120,7 +120,7 @@ any test target and applied to any test:
 The testing library does not assign any semantic meaning to these tags, nor does
 the presence or absence of these tags affect how the testing library runs tests.
 
-## Customizing a tag's appearance
+## Customize a tag's appearance
 
 By default, a tag does not appear in a test's output when the test is run. It is
 possible to assign colors to tags defined in a package so that when the test is
@@ -155,11 +155,3 @@ be set to:
   ".legallyRequired": "#66FFCC"
 }
 ```
-
-## Topics
-
-- ``Trait/tags(_:)-505n9``
-- ``Trait/tags(_:)-yg0i``
-- ``Tag``
-- ``Tag/List``
-- ``Tag()``

Sources/Testing/Testing.docc/AssociatingBugs.md

@@ -23,7 +23,7 @@ specific bugs with tests that reproduce them or verify they are fixed.
   "issues." To avoid confusion with the ``Issue`` type in the testing library,
   this document consistently refers to them as "bugs."
 
-## Associating a bug with a test
+## Associate a bug with a test
 
 To associate a bug with a test, use the ``Trait/bug(_:relationship:_:)-86mmm``
 or ``Trait/bug(_:relationship:_:)-3hsi5`` function. The first argument to this
@@ -43,7 +43,7 @@ specified as a string, it must be parseable as an unsigned integer or as a URL.
 For more information on the formats recognized by the testing library, see
 <doc:BugIdentifiers>.
 
-## Specifying the relationship between a bug and a test
+## Specify the relationship between a bug and a test
 
 By default, the nature of the relationship between a bug and a test is
 unspecified. All the testing library knows about such relationships is that they
@@ -101,10 +101,3 @@ func hasNapkins() async {
   ...
 }
 ```
-
-## Topics
-
-- <doc:BugIdentifiers>
-- ``Trait/bug(_:relationship:_:)-86mmm``
-- ``Trait/bug(_:relationship:_:)-3hsi5``
-- ``Bug``

Sources/Testing/Testing.docc/DefiningTests.md

@@ -20,10 +20,10 @@ This article assumes that the package or project being tested has already been
 configured with a test target. For help configuring a package to use the testing
 library, see <doc:TemporaryGettingStarted>.
 
-## Importing the testing library
+## Import the testing library
 
 To import the testing library, add the following to the Swift source file that
-will contain the test:
+contains the test:
 
 ```swift
 import Testing
@@ -33,11 +33,11 @@ import Testing
   testing library into an application, library, or binary target is not
   supported or recommended. Test functions are not stripped from binaries when
   building for release, so logic and fixtures of a test may be visible to anyone
-  who inspects a build product containing a test function.
+  who inspects a build product that contains a test function.
 
-## Declaring a test function
+## Declare a test function
 
-To declare a test function, write a Swift function declaration that does not
+To declare a test function, write a Swift function declaration that doesn't
 take any arguments, then prefix its name with the `@Test` attribute:
 
 ```swift
@@ -55,7 +55,7 @@ Note that, while this function is a valid test function, it does not actually
 perform any action or test any code. To check for expected values and outcomes
 in test functions, add [expectations](doc:Expectations) to the test function.
 
-## Customizing a test's name
+## Customize a test's name
 
 To customize a test function's name as presented in an IDE or at the command
 line, supply a string literal as an argument to the `@Test` attribute:
@@ -78,7 +78,7 @@ the process), it can be annotated `@MainActor`:
 @Test @MainActor func foodTruckExists() async throws { ... }
 ```
 
-## Limiting the availability of a test
+## Limit the availability of a test
 
 If a test function can only run on newer versions of an operating system or of
 the Swift language, use the `@available` attribute when declaring it. Use the
@@ -90,13 +90,3 @@ a test is unable to run due to limited availability:
 @available(swift, introduced: 8.0, message: "Requires Swift 8.0 features to run")
 @Test func foodTruckExists() { ... }
 ```
-
-## Topics
-
-- ``Test``
-- ``Test(_:_:)``
-
-## See Also
-
-- <doc:Expectations>
-- <doc:ParameterizedTesting>

Sources/Testing/Testing.docc/EnablingAndDisabling.md

@@ -22,9 +22,9 @@ automatically skip them if conditions like these are not met.
 
 - Note: A condition may be evaluated multiple times during testing.
 
-## Disabling a test
+## Disable a test
 
-If a test should be disabled unconditionally, you can use the
+If you need to disable a test unconditionally, use the
 ``Trait/disabled(_:fileID:filePath:line:column:)`` function. Given the following
 test function:
 
@@ -42,17 +42,17 @@ func sellsBurritos() async throws { ... }
 
 The test will now always be skipped.
 
-It is also possible to add a comment to the trait that will be presented in the
-output from the runner when it skips the test:
+It is also possible to add a comment to the trait to present in the output from
+the runner when it skips the test:
 
 ```swift
 @Test("Food truck sells burritos", .disabled("We only sell Thai cuisine"))
 func sellsBurritos() async throws { ... }
 ```
 
-## Conditionally enabling or disabling a test
+## Conditionally enable or disable a test
 
-Sometimes, it makes sense to enable a test only if a condition is met. Consider
+Sometimes, it makes sense to enable a test only when a certain condition is met. Consider
 the following test function:
 
 ```swift
@@ -98,10 +98,10 @@ func isCold() async throws { ... }
 ```
 
 If a test has multiple conditions applied to it, they must _all_ pass for it to
-run. Otherwise, the first condition to fail will be noted as the reason the test
-was skipped.
+run. Otherwise, the test notes the first condition to fail as the reason the test
+is skipped.
 
-## Handling complex conditions
+## Handle complex conditions
 
 If a condition is complex, consider factoring it out into a helper function to
 improve readability:
@@ -116,12 +116,3 @@ func allIngredientsAvailable(for food: Food) -> Bool { ... }
 )
 func makeSundae() async throws { ... }
 ```
-
-## Topics
-
-- ``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:_:)``
-- ``ConditionTrait``

Sources/Testing/Testing.docc/LimitingExecutionTime.md

@@ -1,4 +1,4 @@
-# Limiting the execution time of a test
+# Limiting the running time of tests
 
 <!--
 This source file is part of the Swift.org open source project
@@ -59,8 +59,3 @@ test functions and child test suites within that suite.
 When a time limit is applied to a parameterized test function, it is applied to
 each invocation _separately_ so that if only some arguments cause failures, then
 successful arguments are not incorrectly marked as failing too.
-
-## Topics
-
-- ``Trait/timeLimit(_:)``
-- ``TimeLimitTrait``

Sources/Testing/Testing.docc/MigratingFromXCTest.md

@@ -21,13 +21,13 @@ The testing library provides much of the same functionality of XCTest, but uses
 its own syntax to declare test functions and types. This document covers the
 process of converting XCTest-based content to use the testing library instead.
 
-### Adding the testing library as a dependency
+### Add the testing library as a dependency
 
 Before the testing library can be used, it must be added as a dependency of your
 Swift package or Xcode project. For more information on how to add it, see the
 [Getting Started](doc:TemporaryGettingStarted) guide.
 
-### Importing the testing library
+### Import the testing library
 
 XCTest and the testing library are available from different modules. Instead of 
 importing the XCTest module, import the Testing module:
@@ -51,7 +51,7 @@ A single source file can contain tests written with XCTest as well as other
 tests written with the testing library. Import both XCTest and Testing if a 
 source file contains mixed test content.
 
-### Converting test classes
+### Convert test classes
 
 XCTest groups related sets of test methods in test classes: classes that inherit
 from the [`XCTestCase`](https://developer.apple.com/documentation/xctest/xctestcase)
@@ -92,7 +92,7 @@ If you use a class as a test suite, it must be declared `final`.
 For more information about suites and how to declare and customize them, see
 <doc:OrganizingTests>.
 
-#### Converting setUp() and tearDown() functions
+### Convert setup and teardown functions
 
 In XCTest, code can be scheduled to run before and after a test using the
 [`setUp()`](https://developer.apple.com/documentation/xctest/xctest/3856481-setup)
@@ -169,7 +169,7 @@ implement `deinit`:
   ((103616215)[rdar://103616215])
 -->
 
-### Converting test methods
+### Convert test methods
 
 The testing library represents individual tests as functions, similar to how
 they are represented in XCTest. However, the syntax for declaring a test
@@ -212,7 +212,7 @@ and/or `throws` and to be isolated to a global actor (for example, by using the
 For more information about test functions and how to declare and customize them,
 see <doc:DefiningTests>.
 
-#### Converting XCTAssert() XCTUnwrap(), and XCTFail() calls
+### Check for expected values and outcomes 
 
 XCTest uses a family of approximately 40 functions to assert test requirements.
 These functions are collectively referred to as
@@ -255,6 +255,8 @@ error if its condition is not met:
   }
 }
 
+### Check for optional values
+
 XCTest also has a function, [`XCTUnwrap()`](https://developer.apple.com/documentation/xctest/3380195-xctunwrap),
 that tests if an optional value is `nil` and throws an error if it is. When
 using the testing library, you can use ``require(_:_:sourceLocation:)-6w9oo``
@@ -289,6 +291,8 @@ with optional expressions to unwrap them:
   }
 }
 
+### Record issues
+
 Finally, XCTest has a function, [`XCTFail()`](https://developer.apple.com/documentation/xctest/1500970-xctfail),
 that causes a test to fail immediately and unconditionally. This function is
 useful when the syntax of the language prevents the use of an `XCTAssert()`
@@ -355,7 +359,7 @@ their equivalents in the testing library:
 | `try XCTUnwrap(x)` | `try #require(x)` |
 | `XCTFail("…")` | `Issue.record("…")` |
 
-#### Continuing or halting after test failures
+### Continue or halt after test failures
 
 An instance of an `XCTestCase` subclass can set its
 [`continueAfterFailure`](https://developer.apple.com/documentation/xctest/xctestcase/1496260-continueafterfailure)
@@ -407,7 +411,7 @@ When using either `continueAfterFailure` or
 ``require(_:_:sourceLocation:)-5l63q``, other tests will continue to run after
 the failed test method or test function.
 
-#### Converting XCTestExpectation and XCTWaiter
+### Validate asynchronous behaviors
 
 XCTest has a class, [`XCTestExpectation`](https://developer.apple.com/documentation/xctest/xctestexpectation),
 that represents some asynchronous condition. A developer creates an instance of
@@ -478,7 +482,7 @@ recorded otherwise:
   }
 }
 
-#### Converting XCTSkip(), XCTSkipIf(), and XCTSkipUnless() calls
+### Control whether a test runs
 
 When using XCTest, the [`XCTSkip`](https://developer.apple.com/documentation/xctest/xctskip)
 error type can be thrown to bypass the remainder of a test function. As well,
@@ -518,7 +522,7 @@ test function with an instance of this trait type to control whether it runs:
   }
 }
 
-#### Converting XCTExpectFailure() calls
+### Annotate known issues
 
 A test may have a known issue that sometimes or always prevents it from passing.
 When written using XCTest, such tests can call
@@ -677,3 +681,4 @@ of issues:
 - <doc:DefiningTests>
 - <doc:OrganizingTests>
 - <doc:Expectations>
+- <doc:known-issues>

Sources/Testing/Testing.docc/OrganizingTests.md

@@ -1,4 +1,4 @@
-# Organizing tests
+# Organizing test functions with suite types
 
 <!--
 This source file is part of the Swift.org open source project
@@ -39,7 +39,7 @@ within the scope of the outer test suite type.
 By default, tests contained within a suite will run in parallel with each other.
 For more information about test parallelization, see <doc:Parallelization>.
 
-## Customizing a suite's name
+## Customize a suite's name
 
 To customize a test suite's name, supply a string literal as an argument to the
 `@Suite` attribute:
@@ -162,7 +162,3 @@ class, but it must be declared `final`:
 actor CashRegisterTests: NSObject { ... } // ✅ OK: actors are implicitly final
 class MenuItemTests { ... } // ❌ ERROR: this class is not final
 ```
-
-## Topics
-
-- ``Suite(_:_:)``

Sources/Testing/Testing.docc/Parallelization.md

@@ -1,4 +1,4 @@
-# Parallelizing test execution
+# Running tests serially or in parallel
 
 <!--
 This source file is part of the Swift.org open source project
@@ -65,8 +65,3 @@ disabled (by, for example, passing `--no-parallel` to the `swift test` command.)
 - ``Trait/serial``
 - ``SerialTrait``
 -->
-
-## See Also
-
-- <doc:OrganizingTests>
-- <doc:ParameterizedTesting>