Prefer using raw identifiers over display name parameters for tests and suites.

Sources/Testing/Test+Macro.swift

@@ -86,6 +86,17 @@ public macro Suite(
 /// The use of the `@Suite` attribute is optional; types are recognized as test
 /// suites even if they do not have the `@Suite` attribute applied to them.
 ///
+/// > Tip:
+/// > Give a type a readable name that includes spaces and punctuation by
+/// > surrounding the type's name with backticks, instead of using `@Suite` to
+/// > change its display name:
+/// >
+/// > ```swift
+/// > struct `Delivery region tests` {
+/// >   // Add your tests.
+/// > }
+/// > ```
+///
 /// When adding test functions to a type extension, do not use the `@Suite`
 /// attribute. Only a type's primary declaration may have the `@Suite` attribute
 /// applied to it.
@@ -136,6 +147,13 @@ public macro Test(
 ///     associated function's name.
 ///   - traits: Zero or more traits to apply to this test.
 ///
+/// Surround a test's name with backticks as an alternative to setting the
+/// `displayName` parameter; for example:
+///
+/// ```swift
+/// @Test func `Food truck exists`() { ... }
+/// ```
+///
 /// ## See Also
 ///
 /// - <doc:DefiningTests>
@@ -220,6 +238,13 @@ public macro Test<C>(
 /// that the associated test will run. During testing, the testing library calls
 /// the associated test function once for each element in `collection`.
 ///
+/// Surround a test's name with backticks as an alternative to setting the
+/// `displayName` parameter; for example:
+///
+/// ```swift
+/// @Test func `Food truck exists`() { ... }
+/// ```
+///
 /// @Comment {
 ///   - Bug: The testing library should support variadic generics.
 ///     ([103416861](rdar://103416861))
@@ -276,6 +301,13 @@ extension Test {
 /// testing library calls the associated test function once for each pair of
 /// elements in `collection1` and `collection2`.
 ///
+/// Surround a test's name with backticks as an alternative to setting the
+/// `displayName` parameter; for example:
+///
+/// ```swift
+/// @Test func `Food truck exists`() { ... }
+/// ```
+///
 /// @Comment {
 ///   - Bug: The testing library should support variadic generics.
 ///     ([103416861](rdar://103416861))
@@ -307,6 +339,13 @@ public macro Test<C1, C2>(
 /// testing library calls the associated test function once for each pair of
 /// elements in `collection1` and `collection2`.
 ///
+/// Surround a test's name with backticks as an alternative to setting the
+/// `displayName` parameter; for example:
+///
+/// ```swift
+/// @Test func `Food truck exists`() { ... }
+/// ```
+///
 /// @Comment {
 ///   - Bug: The testing library should support variadic generics.
 ///     ([103416861](rdar://103416861))
@@ -336,6 +375,13 @@ public macro Test<C1, C2>(
 /// library calls the associated test function once for each element in
 /// `zippedCollections`.
 ///
+/// Surround a test's name with backticks as an alternative to setting the
+/// `displayName` parameter; for example:
+///
+/// ```swift
+/// @Test func `Food truck exists`() { ... }
+/// ```
+///
 /// @Comment {
 ///   - Bug: The testing library should support variadic generics.
 ///     ([103416861](rdar://103416861))
@@ -367,6 +413,13 @@ public macro Test<C1, C2>(
 /// library calls the associated test function once for each element in
 /// `zippedCollections`.
 ///
+/// Surround a test's name with backticks as an alternative to setting the
+/// `displayName` parameter; for example:
+///
+/// ```swift
+/// @Test func `Food truck exists`() { ... }
+/// ```
+///
 /// @Comment {
 ///   - Bug: The testing library should support variadic generics.
 ///     ([103416861](rdar://103416861))

Sources/Testing/Testing.docc/DefiningTests.md

@@ -37,14 +37,14 @@ 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
-@Test func foodTruckExists() {
+@Test func `Food truck exists`() {
   // Test logic goes here.
 }
 ```
 
 This test function can be present at file scope or within a type. A type
-containing test functions is automatically a _test suite_ and can be optionally
-annotated with the `@Suite` attribute. For more information about suites, see
+containing test functions is automatically a _test suite_ and you can optionally
+annotate it with the `@Suite` attribute. For more information about suites, see
 <doc:OrganizingTests>.
 
 Note that, while this function is a valid test function, it doesn't actually
@@ -71,7 +71,7 @@ to run in the main actor's execution context (that is, from the main thread of
 the process), it can be annotated `@MainActor`:
 
 ```swift
-@Test @MainActor func foodTruckExists() async throws { ... }
+@Test @MainActor func `Food truck exists`() async throws { ... }
 ```
 
 ### Limit the availability of a test

Sources/Testing/Testing.docc/OrganizingTests.md

@@ -38,13 +38,23 @@ within the scope of the outer test suite type.
 By default, tests contained within a suite run in parallel with each other.
 For more information about test parallelization, see <doc:Parallelization>.
 
-### Customize a suite's name
+### Name a test suite
 
-To customize a test suite's name, supply a string literal as an argument to the
-`@Suite` attribute:
+The testing library uses the name of the Swift type as the test suite's name.
+Surround the type's name with backticks to use spaces and punctuation characters
+in the name:
 
 ```swift
-@Suite("Food truck tests") struct FoodTruckTests {
+struct `Food truck tests: existence` {
+  @Test func `Food truck exists`() { ... }
+}
+```
+
+Alternatively, customize a test suite's name by supplying a string literal as an
+argument to the `@Suite` attribute:
+
+```swift
+@Suite("Food truck tests: existence") struct FoodTruckTests {
   @Test func foodTruckExists() { ... }
 }
 ```