Cleanup user docs

include/swift/AST/DiagnosticGroups.def

@@ -44,6 +44,7 @@ GROUP(ActorIsolatedCall, "actor-isolated-call")
 GROUP(AlwaysAvailableDomain, "always-available-domain")
 GROUP(AvailabilityUnrecognizedName, "availability-unrecognized-name")
 GROUP(ClangDeclarationImport, "clang-declaration-import")
+GROUP(CompilationCaching, "compilation-caching")
 GROUP(ConformanceIsolation, "conformance-isolation")
 GROUP(DeprecatedDeclaration, "deprecated-declaration")
 GROUP(DynamicCallable, "dynamic-callable-requirements")
@@ -52,6 +53,7 @@ GROUP(ErrorInFutureSwiftVersion, "error-in-future-swift-version")
 GROUP(ExclusivityViolation, "exclusivity-violation")
 GROUP(ExistentialAny, "existential-any")
 GROUP(ExistentialMemberAccess, "existential-member-access-limitations")
+GROUP(ExistentialType, "existential-type")
 GROUP(ImplementationOnlyDeprecated, "implementation-only-deprecated")
 GROUP(IsolatedConformances, "isolated-conformances")
 GROUP(MemberImportVisibility, "member-import-visibility")
@@ -63,27 +65,30 @@ GROUP(MutableGlobalVariable, "mutable-global-variable")
 GROUP(NominalTypes, "nominal-types")
 GROUP(NonisolatedNonsendingByDefault, "nonisolated-nonsending-by-default")
 GROUP(OpaqueTypeInference, "opaque-type-inference")
+GROUP(PerformanceHints, "performance-hints")
 GROUP(PreconcurrencyImport, "preconcurrency-import")
 GROUP(PropertyWrappers, "property-wrapper-requirements")
 GROUP(ProtocolTypeNonConformance, "protocol-type-non-conformance")
+GROUP(RegionIsolation, "region-isolation")
 GROUP(ResultBuilderMethods, "result-builder-methods")
+GROUP(ReturnTypeImplicitCopy, "return-type-implicit-copy")
 GROUP(SendableClosureCaptures, "sendable-closure-captures")
 GROUP(SendableMetatypes, "sendable-metatypes")
+GROUP(SendingClosureRisksDataRace, "sending-closure-risks-data-race")
 GROUP(SendingRisksDataRace, "sending-risks-data-race")
 GROUP(StrictLanguageFeatures, "strict-language-features")
 GROUP(StrictMemorySafety, "strict-memory-safety")
 GROUP(StringInterpolationConformance, "string-interpolation-conformance")
 GROUP(TemporaryPointers, "temporary-pointers")
 GROUP(TrailingClosureMatching, "trailing-closure-matching")
 GROUP(UnknownWarningGroup, "unknown-warning-group")
-GROUP(CompilationCaching, "compilation-caching")
 GROUP(WeakMutability, "weak-mutability")
 
-GROUP(PerformanceHints, "performance-hints")
-GROUP(ReturnTypeImplicitCopy, "return-type-implicit-copy")
-GROUP_LINK(PerformanceHints, ReturnTypeImplicitCopy)
-GROUP(ExistentialType, "existential-type")
 GROUP_LINK(PerformanceHints, ExistentialType)
+GROUP_LINK(PerformanceHints, ReturnTypeImplicitCopy)
+
+GROUP_LINK(RegionIsolation, SendingClosureRisksDataRace)
+GROUP_LINK(RegionIsolation, SendingRisksDataRace)
 
 #define UNDEFINE_DIAGNOSTIC_GROUPS_MACROS
 #include "swift/AST/DefineDiagnosticGroupsMacros.h"

include/swift/AST/DiagnosticsSIL.def

@@ -1075,7 +1075,7 @@ NOTE(regionbasedisolation_typed_tns_passed_to_sending, none,
      "causing races inbetween %0 uses and uses reachable from the callee",
      (StringRef, Type))
 
-ERROR(regionbasedisolation_typed_tns_passed_sending_closure, none,
+GROUPED_ERROR(regionbasedisolation_typed_tns_passed_sending_closure, SendingClosureRisksDataRace, none,
      "passing closure as a 'sending' parameter risks causing data races between %0 and concurrent execution of the closure",
      (StringRef))
 NOTE(regionbasedisolation_typed_tns_passed_to_sending_closure_helper_have_value, none,

userdocs/diagnostics/actor-isolated-call.md

@@ -1,4 +1,6 @@
-# Calling an actor-isolated method from a synchronous nonisolated context
+# Calling an actor-isolated method from a synchronous nonisolated context (ActorIsolatedCall)
+
+## Overview
 
 Accessing actor-isolated state from outside the actor can cause data races in your program. Resolve this error by calling actor-isolated functions on the actor.
 

userdocs/diagnostics/conformance-isolation.md

@@ -1,4 +1,6 @@
-# Protocol conformances crossing into actor-isolated code
+# Protocol conformances crossing into actor-isolated code (ConformanceIsolation)
+
+## Overview
 
 Protocol conformances crossing into actor-isolated code can cause data races in your program. Resolve this error by ensuring access to isolated state is always done within the actor.
 

userdocs/diagnostics/diagnostic-groups.md

@@ -2,14 +2,14 @@
 
 <!-- This file is auto-generated via `swift swift/utils/generate-doc-index.swift` -->
 
-Diagnostic groups allow controlling the behavior of warnings in a more precise manner.
+Detailed explanations for various compiler diagnostics.
 
 
 ## Overview
 
 Diagnostic groups collect some number of diagnostics together under a common group name. This allows
 for extra documentation to help explain relevant language concepts, as well as the ability to
-control the behavior of warnings in a more precise manner:
+control the behavior of warnings in a more precise manner (when that group contains warnings):
 - `-Werror <group>` - upgrades warnings in the specified group to errors
 - `-Wwarning <group>` - indicates that warnings in the specified group should remain warnings, even
   if they were previously upgraded to errors
@@ -24,18 +24,59 @@ Or upgrade all warnings except deprecated declaration to errors:
 -warnings-as-errors -Wwarning DeprecatedDeclaration
 ```
 
+## Groups with warnings
+- <doc:always-available-domain>
+- <doc:trailing-closure-matching>
+- <doc:compilation-caching>
+- <doc:string-interpolation-conformance>
+- <doc:deprecated-declaration>
+- <doc:implementation-only-deprecated>
+- <doc:embedded-restrictions>
+- <doc:preconcurrency-import>
+- <doc:clang-declaration-import>
+- <doc:isolated-conformances>
+- <doc:error-in-future-swift-version>
+- <doc:module-version-missing>
+- <doc:result-builder-methods>
+- <doc:strict-language-features>
+- <doc:strict-memory-safety>
+- <doc:unknown-warning-group>
 
-## Topics
 
+## Topics
+- <doc:dynamic-callable-requirements>
+- <doc:always-available-domain>
+- <doc:trailing-closure-matching>
+- <doc:actor-isolated-call>
+- <doc:sendable-closure-captures>
 - <doc:compilation-caching>
+- <doc:string-interpolation-conformance>
 - <doc:deprecated-declaration>
 - <doc:implementation-only-deprecated>
 - <doc:embedded-restrictions>
 - <doc:preconcurrency-import>
 - <doc:clang-declaration-import>
+- <doc:isolated-conformances>
+- <doc:error-in-future-swift-version>
 - <doc:missing-module-on-known-paths>
 - <doc:module-version-missing>
+- <doc:module-not-testable>
+- <doc:multiple-inheritance>
+- <doc:nominal-types>
+- <doc:exclusivity-violation>
+- <doc:performance-hints>
+- <doc:property-wrapper-requirements>
+- <doc:conformance-isolation>
+- <doc:protocol-type-non-conformance>
+- <doc:result-builder-methods>
+- <doc:sendable-metatypes>
+- <doc:sending-closure-risks-data-race>
+- <doc:sending-risks-data-race>
 - <doc:strict-language-features>
 - <doc:strict-memory-safety>
+- <doc:temporary-pointers>
+- <doc:opaque-type-inference>
 - <doc:unknown-warning-group>
 - <doc:availability-unrecognized-name>
+- <doc:mutable-global-variable>
+- <doc:existential-member-access-limitations>

userdocs/diagnostics/diagnostics.md

@@ -9,6 +9,5 @@ Documentation on diagnostics emitted by the compiler and settings that control t
 
 ## Topics
 
-- <doc:diagnostic-descriptions>
 - <doc:diagnostic-groups>
 - <doc:upcoming-language-features>

userdocs/diagnostics/dynamic-callable-requirements.md

@@ -1,4 +1,7 @@
-# @dynamicCallable Implementation Requirements
+# @dynamicCallable implementation requirements (DynamicCallable)
+
+## Overview
+
 If a type is marked with the `@dynamicCallable` attribute, it must provide a valid implementation of `dynamicallyCall(withArguments:)`, `dynamicallyCall(withKeywordArguments:)`, or both. If it fails to do so, an error will be reported at compile-time. Note that an implementation of `dynamicallyCall(withKeywordArguments:)` is required to support calls with keyword arguments.
 
 To be considered valid, an implementation of `dynamicallyCall(withArguments:)` must:
@@ -10,4 +13,8 @@ To be considered valid, an implementation of `dynamicallyCall(withKeywordArgumen
 - Be an instance method. `static` or `class` implementations are not allowed.
 - Have an argument type which conforms to the `ExpressibleByDictionaryLiteral` protocol. This can be `Dictionary`, `KeyValuePairs` (which may be used to support duplicated keyword arguments), or some other conforming type.
 - The `Key` associated type of the argument type must conform to the `ExpressibleByStringLiteral` protocol. This type is used to represent the dynamic argument keywords.
-- The `Value` associated type of the argument type and the return type of `dynamicallyCall(withKeywordArguments:)` may be any valid types.
+- The `Value` associated type of the argument type and the return type of `dynamicallyCall(withKeywordArguments:)` may be any valid types.
+
+## See also
+
+- [SE-0216](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0216-dynamic-callable.md)

userdocs/diagnostics/error-in-future-swift-version.md

@@ -1,4 +1,6 @@
-# Language mode and tools version
+# Language mode and tools version (ErrorInFutureSwiftVersion)
+
+## Overview
 
 Swift language mode and Swift compiler tools version are distinct concepts. One compiler version can support multiple language modes.
 
@@ -7,6 +9,6 @@ There are two related kinds of "Swift version" that are distinct:
 * Swift tools version: the version number of the compiler itself. For example, the Swift 5.6 compiler was introduced in March 2022.
 * Swift language mode version: the language mode version with which we are providing source compatibility. For example, the Swift 5 language mode is the most current language mode version supported by Swift tools version 5.10.
 
-The Swift tools support multiple Swift language modes. All Swift tools versions between 5.0 and 5.10 support three Swift language modes: 4, 4.2, and 5. The Swift 6.0 compiler supports four Swift language modes: 4, 4.2, 5, and 6. Swift language modes are opt-in; when you use a tools version that supports a new language mode, your code will not build with the new language mode until you set that language mode in your build settings with `-swift-version X`.
+The Swift tools support multiple Swift language modes. All Swift tools versions between 5.0 and 5.10 support three Swift language modes: 4, 4.2, and 5. The Swift 6.0 compiler supports four Swift language modes: 4, 4.2, 5, and 6. Swift language modes are opt-in; when you use a tools version that supports a new language mode, your code will not build with the new language mode until you set that language mode in your build settings with `-language-mode X`.
 
 A warning suffixed with `this is an error in the Swift 6 language mode` means that once you migrate to that language mode in your code, the warning will be promoted to an error. These warnings primarily come from enabling upcoming features that are enabled by default in that language mode version, but errors may also be staged in as warnings until the next language mode to maintain source compatibility when fixing compiler bugs.

userdocs/diagnostics/exclusivity-violation.md

@@ -1,4 +1,6 @@
-# Overlapping accesses, but operation requires exclusive access
+# Overlapping accesses, but operation requires exclusive access (ExclusivityViolation)
+
+## Overview
 
 Swift requires exclusive access to a variable in order to modify that variable. An error is reported if a program attempts to access a variable while it is already in the process of being accessed via another name. These issues can often be resolved by making a local copy of a variable before modifying it.
 
@@ -58,4 +60,10 @@ var toAppend = numbers
 numbers.append(removingFrom: &toAppend)
 ```
 
-Exclusivity checks play an important role in enforcing memory safety and enabling compiler optimizations. To learn more, see [Swift 5 Exclusivity Enforcement](https://www.swift.org/blog/swift-5-exclusivity/) on the Swift.org blog.
+Exclusivity checks play an important role in enforcing memory safety and enabling compiler optimizations. See the Swift.org [blog][exclusivity-enforcement] to learn more.
+
+## See Also
+
+- [Swift 5 exclusivity enforcement][exclusivity-enforcement]
+
+[exclusivity-enforcement]: https://www.swift.org/blog/swift-5-exclusivity/

userdocs/diagnostics/existential-member-access-limitations.md

@@ -1,4 +1,4 @@
-# Using Protocol Members with References to `Self` or `Self`-rooted Associated Types
+# Using protocol members with references to `Self` or `Self`-rooted associated types (ExistentialMemberAccess)
 
 Protocol requirements and protocol extension members may be accessed via a conformance constraint on a generic parameter, an opaque result type, or via the protocol type itself:
 
@@ -51,4 +51,16 @@ func duplicateShape(_ shape: Shape) -> Shape {
 }
 ```
 
-Most use cases involving usage of protocol members that fall under the above restriction can instead be supported by constrained generics, opaque result types, or manual type-erasing wrappers. To learn more, see the sections on [protocols](https://docs.swift.org/swift-book/LanguageGuide/Protocols.html), [generics](https://docs.swift.org/swift-book/LanguageGuide/Generics.html), and [opaque types](https://docs.swift.org/swift-book/LanguageGuide/OpaqueTypes.html) in the Language Guide. For a better understanding of existential types in particular, and an in-depth exploration of the relationships among these built-in abstraction models, we recommend reading the [design document for improving the UI of the generics model](https://forums.swift.org/t/improving-the-ui-of-generics/22814).
+Most use cases involving usage of protocol members that fall under the above restriction can instead be supported by constrained generics, opaque result types, or manual type-erasing wrappers. To learn more, see the sections on [protocols], [generics], and [opaque types][opaque-types] in the Language Guide. For a better understanding of existential types in particular, and an in-depth exploration of the relationships among these built-in abstraction models, we recommend reading [design document for improving the UI of the generics model][improving-generics-ui].
+
+## See Also
+
+- [Generics][generics]
+- [Improving the UI of generics][improving-generics-ui]
+- [Opaque Types][opaque-types]
+- [Protocols][protocols]
+
+[generics]: https://docs.swift.org/swift-book/documentation/the-swift-programming-language/generics
+[improving-generics-ui]: https://forums.swift.org/t/improving-the-ui-of-generics/22814
+[opaque-types]: https://docs.swift.org/swift-book/documentation/the-swift-programming-language/opaquetypes
+[protocols]: https://docs.swift.org/swift-book/documentation/the-swift-programming-language/protocols

userdocs/diagnostics/implementation-only-deprecated.md

@@ -2,11 +2,12 @@
 
 Warnings that identify `import` declarations with the `@_implementationOnly` attribute.
 
+
 ## Overview
 
 When applied to `import` declarations, the compiler-internal attribute `@_implementationOnly` attempts prevents declarations from the imported module from being exposed in the ABI or public interface of the dependent module. This attribute became deprecated when support for access levels on `import` declarations was introduced with [SE-0409].
 
-One reason `@_implementationOnly import` is deprecated is that it is unsafe when used in modules that are built _without_ [library evolution] enabled. For example, suppose the following code were part of a library named `Foo`:
+One reason `@_implementationOnly import` is deprecated is that it is unsafe when used in modules that are built _without_ [library evolution][library-evolution] enabled. For example, suppose the following code were part of a library named `Foo`:
 
 ```swift
 // Library `Foo`
@@ -19,5 +20,10 @@ public struct Bar {
 
 If `Foo` is not compiled with library evolution, then the memory layout of values of `Bar` must be known at compile time in clients of `Foo`. However, the `@_implementationOnly import` of `ImplementationDetail` prevents clients from being able to look up `Baz` which is a type that contributes to the layout of `Foo`. As a result, the layout of `Foo` will be miscalculated resulting in undefined behavior.
 
+## See Also
+
+- [SE-0409: Access level on imports][SE-0409]
+- [Library evolution][library-evolution]
+
 [SE-0409]: https://github.com/swiftlang/swift-evolution/blob/main/proposals/0409-access-level-on-imports.md
-[library evolution]: https://www.swift.org/blog/library-evolution/
+[library-evolution]: https://www.swift.org/blog/library-evolution/

userdocs/diagnostics/isolated-conformances.md

@@ -1,4 +1,6 @@
-# Isolated conformances
+# Isolated conformances (IsolatedConformances)
+
+## Overview
 
 Using an isolated conformance from outside the actor can cause data races in your program. Resolve these errors by only using isolated conformances within the actor.
 

userdocs/diagnostics/module-not-testable.md

@@ -1,5 +1,7 @@
-# Module not testable
+# Module not testable (ModuleNotTestable)
+
+## Overview
 
 Modules imported using `@testable import` must have been compiled using the `-enable-testing` compiler flag.
 
-`@testable import` allows clients of a module to access `internal` API when writing tests. A `@testable import` will report an error if the imported module was not compiled with the `-enable-testing` compiler flag. Use of `-enable-testing` is recommended only in debug builds or other builds not intended for production use.
+`@testable import` allows clients of a module to access `internal` API when writing tests. A `@testable import` will report an error if the imported module was not compiled with the `-enable-testing` compiler flag. Use of `-enable-testing` is recommended only in debug builds or other builds not intended for production use.