Proofread pass of the articles

Sources/Testing/Testing.docc/AddingComments.md

@@ -14,11 +14,11 @@ Add comments to provide useful information about tests.
 
 ## Overview
 
-It is often useful to add comments to code in order:
+It's often useful to add comments to code to:
 
-- to provide context or background information about the code's purpose;
-- to explain how complex code implemented; or
-- to include details which may be helpful when diagnosing issues.
+- Provide context or background information about the code's purpose
+- Explain how complex code implemented
+- Include details which may be helpful when diagnosing issues
 
 Test code is no different and can benefit from explanatory code comments, but
 often test issues are shown in places where the source code of the test is
@@ -44,7 +44,7 @@ immediately before its `@Test` or `@Suite` attribute:
 }
 ```
 
-The comment `"// Assumes the standard lunch menu includes a taco"` will be added
+The comment, `// Assumes the standard lunch menu includes a taco`, is added
 to the test.
 
 The following language comment styles are supported:
@@ -61,7 +61,7 @@ The following language comment styles are supported:
 Test comments which are automatically added from source code comments preserve
 their original formatting, including any prefixes like `//` or `/**`. This
 is because the whitespace and formatting of comments can be meaningful in some
-circumstances or aid in understanding the comment—for example, when a comment
+circumstances or aid in understanding the comment — for example, when a comment
 includes an example code snippet or diagram.
 
 <!-- FIXME: Uncomment this section if/when the `.comment(...)` trait is promoted
@@ -88,10 +88,10 @@ func lunchMenu() {
 
 ## Use test comments effectively
 
-As in normal code, comments on tests are generally most useful when:
+As in normal code, comments on tests are generally most useful when they:
 
-- they add information that isn't obvious from reading the code; or
-- they provide useful information about the operation or motivation of a test.
+- Add information that isn't obvious from reading the code
+- Provide useful information about the operation or motivation of a test
 
 If a test is related to a bug or issue, consider using the ``Bug`` trait instead
-of comments. For more information, review <doc:AssociatingBugs>.
+of comments. For more information, see <doc:AssociatingBugs>.

Sources/Testing/Testing.docc/AddingTags.md

@@ -16,8 +16,8 @@ Use tags to provide semantic information for organization, filtering, and custom
 
 A complex package or project may contain hundreds or thousands of tests and
 suites. Some subset of those tests may share some common facet, such as being
-"critical" or "flaky". The testing library includes a type of trait called
-"tags" that can be added to tests to group and categorize them.
+_critical_ or _flaky_. The testing library includes a type of trait called
+_tags_ that you can add to group and categorize tests.
 
 Tags are different from test suites: test suites impose structure on test
 functions at the source level, while tags provide semantic information for a
@@ -31,7 +31,7 @@ a sequence of tags as its argument, and those tags are then applied to the
 corresponding test at runtime. If any tags are applied to a test suite, then all
 tests in that suite inherit those tags.
 
-The testing library does not assign any semantic meaning to any tags, nor does
+The testing library doesn't assign any semantic meaning to any tags, nor does
 the presence or absence of tags affect how the testing library runs tests.
 
 Tags themselves are instances of ``Tag`` and can be expressed as string
@@ -52,7 +52,7 @@ If two tags with the same name (`legallyRequired` in the above example) are
 declared in different files, modules, or other contexts, the testing library
 treats them as equivalent.
 
-If it is important for a tag to be distinguished from similar tags declared
+If it's important for a tag to be distinguished from similar tags declared
 elsewhere in a package or project (or its dependencies), use
  [reverse-DNS naming](https://en.wikipedia.org/wiki/Reverse_domain_name_notation)
 to create a unique Swift symbol name for your tag:
@@ -82,10 +82,10 @@ The following example is unsupported:
 
 ```swift
 extension Tag {
-  @Tag static var legallyRequired: Self // ✅ OK: declaring a new tag
+  @Tag static var legallyRequired: Self // ✅ OK: Declaring a new tag.
 
-  static var requiredByLaw: Self { // ❌ ERROR: this tag name will not be
-                                   // recognized at runtime
+  static var requiredByLaw: Self { // ❌ ERROR: This tag name isn't
+                                   // recognized at runtime.
     legallyRequired
   }
 }
@@ -97,11 +97,11 @@ declaration), it cannot be applied to test functions or test suites. The
 following declarations are unsupported:
 
 ```swift
-@Tag let needsKetchup: Self // ❌ ERROR: tags must be declared in an extension
-                            // to Tag
+@Tag let needsKetchup: Self // ❌ ERROR: Tags must be declared in an extension
+                            // to Tag.
 struct Food {
-  @Tag var needsMustard: Self // ❌ ERROR: tags must be declared in an extension
-                              // to Tag
+  @Tag var needsMustard: Self // ❌ ERROR: Tags must be declared in an extension
+                              // to Tag.
 }
 ```
 
@@ -110,7 +110,7 @@ HIDDEN: tag colors are experimental SPI.
 
 ## Built-in tags
 
-The testing library predefines the following symbolic tags that can be used in
+The testing library predefines the following symbolic tags that you can use in
 any test target and applied to any test:
 
 - ``Tag/red``
@@ -120,18 +120,18 @@ any test target and applied to any test:
 - ``Tag/blue``
 - ``Tag/purple``
 
-The testing library does not assign any semantic meaning to these tags, nor does
+The testing library doesn't assign any semantic meaning to these tags, nor does
 the presence or absence of these tags affect how the testing library runs tests.
 
 ## Customize a tag's appearance
 
-By default, a tag does not appear in a test's output when the test is run. It is
+By default, a tag doesn't appear in a test's output when the test is run. It's
 possible to assign colors to tags defined in a package so that when the test is
 run, the tag is visible in its output.
 
 To add colors to tags, create a directory in your home directory named
 `".swift-testing"` and add a file named `"tag-colors.json"` to it. This file
-should contain a JSON object (a dictionary) whose keys are strings representing
+should contain a JSON object (a dictionary) whose keys are strings that represent
 tags and whose values represent tag colors.
 
 - Note: On Windows, create the `".swift-testing"` directory in the
@@ -141,15 +141,15 @@ tags and whose values represent tag colors.
 Tag colors can be represented using several formats:
 
 - The strings `"red"`, `"orange"`, `"yellow"`, `"green"`, `"blue"`, or
-  `"purple"`, representing corresponding predefined instances of ``Tag``, i.e.
+  `"purple"`, representing corresponding predefined instances of ``Tag``, like
   ``Tag/red``, ``Tag/orange``, ``Tag/yellow``, ``Tag/green``, ``Tag/blue``, and
-  ``Tag/purple``;
+  ``Tag/purple``.
 - A string of the form `"#RRGGBB"`, containing a hexadecimal representation of
-  the color in a device-independent RGB color space; or
-- The `null` literal value, representing "no color."
+  the color in a device-independent RGB color space.
+- The `null` literal value, which represents no color.
 
-For example, to set the color of the tag `"critical"` to orange and the color of
-the tag `.legallyRequired` to teal, the contents of `"tag-colors.json"` can
+For example, to set the color of the `"critical"` tag to orange and the color of
+the `.legallyRequired` tag to teal, the contents of `"tag-colors.json"` can
 be set to:
 
 ```json

Sources/Testing/Testing.docc/AssociatingBugs.md

@@ -15,8 +15,8 @@ Associate bugs uncovered or verified by tests.
 ## Overview
 
 Tests allow developers to prove that the code they write is working as expected.
-If code is not working correctly, bug trackers are often used to track the work
-necessary to fix the underlying problem. It is often useful to associate
+If code isn't working correctly, bug trackers are often used to track the work
+necessary to fix the underlying problem. It's often useful to associate
 specific bugs with tests that reproduce them or verify they are fixed.
 
 - Note: "Bugs" as described in this document may also be referred to as

Sources/Testing/Testing.docc/BugIdentifiers.md

@@ -10,7 +10,7 @@ See https://swift.org/LICENSE.txt for license information
 See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 -->
 
-How the testing library interprets bug identifiers provided by developers.
+Examine how the testing library interprets bug identifiers provided by developers.
 
 ## Overview
 
@@ -21,17 +21,17 @@ formats are associated with some common bug-tracking systems.
   "issues." To avoid confusion with the ``Issue`` type in the testing library,
   this document consistently refers to them as "bugs."
 
-## Recognized formats
+### Recognized formats
 
 - If the bug identifier begins with `"rdar:"`, it is assumed to represent a bug
   filed with Apple's Radar system.
 - If the bug identifier can be parsed as a URL according to
   [RFC 3986](https://www.ietf.org/rfc/rfc3986.txt), it is assumed to represent
   an issue tracked at that URL.
 - If the bug identifier begins with `"FB"` and the rest of it can be parsed as
-  an unsigned integer, it is assumed to represent a bug filed with the
+  an unsigned integer, it's assumed to represent a bug filed with the
   [Apple Feedback Assistant](https://feedbackassistant.apple.com).
-- If the bug identifier can be parsed as an unsigned integer, it is assumed to
+- If the bug identifier can be parsed as an unsigned integer, it's assumed to
   represent an issue with that numeric identifier in an unspecified bug-tracking
   system.
 - All other bug identifiers are considered invalid and will cause the compiler
@@ -46,9 +46,9 @@ handling to detect:
   the same repository as the test.
 -->
 
-## Examples
+### Examples
 
-| Trait Function | Valid | Inferred Bug-Tracking System |
+| Trait function | Valid | Inferred bug-tracking system |
 |-|:-:|-|
 | `.bug(12345)` | Yes | None |
 | `.bug("12345")` | Yes | None |

Sources/Testing/Testing.docc/DefiningTests.md

@@ -20,7 +20,7 @@ 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>.
 
-## Import the testing library
+### Import the testing library
 
 To import the testing library, add the following to the Swift source file that
 contains the test:
@@ -30,12 +30,12 @@ import Testing
 ```
 
 - Note: Only import the testing library into a test target. Importing the
-  testing library into an application, library, or binary target is not
-  supported or recommended. Test functions are not stripped from binaries when
+  testing library into an application, library, or binary target isn't
+  supported or recommended. Test functions aren't stripped from binaries when
   building for release, so logic and fixtures of a test may be visible to anyone
   who inspects a build product that contains a test function.
 
-## Declare a test function
+### Declare a test function
 
 To declare a test function, write a Swift function declaration that doesn't
 take any arguments, then prefix its name with the `@Test` attribute:
@@ -51,11 +51,11 @@ containing test functions is automatically a _test suite_ and can be optionally
 annotated with the `@Suite` attribute. For more information about suites, see
 <doc:OrganizingTests>.
 
-Note that, while this function is a valid test function, it does not actually
+Note that, while this function is a valid test function, it doesn't 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.
 
-## Customize 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:
@@ -67,7 +67,7 @@ line, supply a string literal as an argument to the `@Test` attribute:
 To further customize the appearance and behavior of a test function, use
  [traits](doc:Traits) such as ``Trait/tags(_:)-505n9``.
 
-## Writing concurrent or throwing tests
+### Write concurrent or throwing tests
 
 As with other Swift functions, test functions can be marked `async` and `throws`
 to annotate them as concurrent or throwing, respectively. If a test is only safe
@@ -78,7 +78,7 @@ the process), it can be annotated `@MainActor`:
 @Test @MainActor func foodTruckExists() async throws { ... }
 ```
 
-## Limit 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

Sources/Testing/Testing.docc/EnablingAndDisabling.md

@@ -3,7 +3,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
@@ -14,15 +14,15 @@ Conditionally enable or disable individual tests before they run.
 
 ## Overview
 
-Often, a test will only be applicable in specific circumstances. For instance,
+Often, a test is only applicable in specific circumstances. For instance,
 you might want to write a test that only runs on devices with particular
 hardware capabilities, or performs locale-dependent operations. The testing
 library allows you to add traits to your tests that cause runners to
 automatically skip them if conditions like these are not met.
 
 - Note: A condition may be evaluated multiple times during testing.
 
-## Disable a test
+### Disable a test
 
 If you need to disable a test unconditionally, use the
 ``Trait/disabled(_:fileID:filePath:line:column:)`` function. Given the following
@@ -42,15 +42,15 @@ func sellsBurritos() async throws { ... }
 
 The test will now always be skipped.
 
-It is also possible to add a comment to the trait to present in the output from
+It's 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 enable or disable a test
+### Enable or disable a test conditionally
 
 Sometimes, it makes sense to enable a test only when a certain condition is met. Consider
 the following test function:
@@ -60,17 +60,16 @@ the following test function:
 func isCold() async throws { ... }
 ```
 
-If it is currently winter, then presumably ice cream will not be available for
-sale and this test will fail. It therefore makes sense to only enable it if it
-is currently summer. You can conditionally enable a test with
+If it's currently winter, then presumably ice cream won't be available for
+sale and this test will fail. It therefore makes sense to only enable it if it's currently summer. You can conditionally enable a test with
 ``Trait/enabled(if:_:fileID:filePath:line:column:)``:
 
 ```swift
 @Test("Ice cream is cold", .enabled(if: Season.current == .summer))
 func isCold() async throws { ... }
 ```
 
-It is also possible to conditionally _disable_ a test and to combine multiple
+It's also possible to conditionally _disable_ a test and to combine multiple
 conditions:
 
 ```swift
@@ -100,7 +99,7 @@ If a test has multiple conditions applied to it, they must _all_ pass for it to
 run. Otherwise, the test notes the first condition to fail as the reason the test
 is skipped.
 
-## Handle complex conditions
+### Handle complex conditions
 
 If a condition is complex, consider factoring it out into a helper function to
 improve readability:

Sources/Testing/Testing.docc/LimitingExecutionTime.md

@@ -3,7 +3,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
@@ -19,8 +19,7 @@ resources to complete, may rely on downloaded data from a server, or may
 otherwise be dependent on external factors.
 
 If a test may hang indefinitely or may consume too many system resources to
-complete effectively, consider setting a time limit for it so that it will
-be marked as failing if it runs for an excessive amount of time. Use the
+complete effectively, consider setting a time limit for it so that it's marked as failing if it runs for an excessive amount of time. Use the
 ``Trait/timeLimit(_:)`` trait as an upper bound:
 
 ```swift
@@ -34,13 +33,13 @@ func serve100CustomersInOneHour() async {
 }
 ```
 
-If the above test function takes longer than 60 &times; 60 seconds (i.e. one
-hour) to execute, the task in which it is running will be
+If the above test function takes longer than an
+hour (60 x 60 seconds) to execute, the task in which it's running is
 [cancelled](https://developer.apple.com/documentation/swift/task/cancel())
-and the test will fail with an issue of kind
+and the test fails with an issue of kind
 ``Issue/Kind-swift.enum/timeLimitExceeded(timeLimitComponents:)``.
 
-- Note: if multiple time limit traits apply to a test, the shortest time limit
+- Note: If multiple time limit traits apply to a test, the shortest time limit
   is used.
 
 The testing library may adjust the specified time limit for performance reasons
@@ -51,11 +50,11 @@ limit traits.
 
 ### Time limits applied to test suites
 
-When a time limit is applied to a test suite, it is recursively applied to all
+When a time limit is applied to a test suite, it's recursively applied to all
 test functions and child test suites within that suite.
 
 ### Time limits applied to parameterized tests
 
-When a time limit is applied to a parameterized test function, it is applied to
+When a time limit is applied to a parameterized test function, it's applied to
 each invocation _separately_ so that if only some arguments cause failures, then
-successful arguments are not incorrectly marked as failing too.
+successful arguments aren't incorrectly marked as failing too.