Add groupings for the various diagnostics

userdocs/diagnostics/clang-declaration-import.md

@@ -1,7 +1,9 @@
-# Imported Clang Declaration Warnings (`ClangDeclarationImport`)
+# Imported Clang declaration warnings (ClangDeclarationImport)
 
+Covers all warnings related to malformed APIs that are imported into Swift from C, C++, and Obj-C headers.
 
-This diagnostic group covers all warnings related to malformed APIs that are imported into Swift from C, C++, and Obj-C headers.
+
+## Overview
 
 As one example of a potential malformed API diagnostic, suppose a Clang module dependency contained the following declaration:
 

userdocs/diagnostics/deprecated-declaration.md

@@ -1,7 +1,8 @@
-# Deprecated Declaration Warnings (`DeprecatedDeclaration`)
+# Deprecated declaration warnings (DeprecatedDeclaration)
 
+Warnings related to deprecated APIs that may be removed in future versions and should be replaced with more current alternatives.
 
-This diagnostic group includes warnings related to deprecated APIs that may be removed in future versions and should be replaced with more current alternatives.
+## Overview
 
 The `DeprecatedDeclaration` group covers the following warnings:
 - Use of a function annotated with `@available(<platform>, deprecated: <version>)`
@@ -65,10 +66,3 @@ The `DeprecatedDeclaration` group covers the following warnings:
     func enqueue(_ job: __owned Job) {} // 'Executor.enqueue(Job)' is deprecated as a protocol requirement; conform type 'C' to 'Executor' by implementing 'func enqueue(ExecutorJob)' instead
   }
   ```
-
-## Usage Example
-
-```sh
-swiftc -Werror DeprecatedDeclaration file.swift
-swiftc -warnings-as-errors -Wwarning DeprecatedDeclaration file.swift
-```

userdocs/diagnostics/diagnostics.md

@@ -1,7 +1,14 @@
-# Swift Compiler Diagnostics
+# Swift compiler diagnostics
 
 @Metadata {
    @TechnologyRoot
 }
 
-Documentation on diagnostics emitted by the compiler.
+Documentation on diagnostics emitted by the compiler and settings that control them.
+
+
+## Topics
+
+- <doc:diagnostic-descriptions>
+- <doc:diagnostic-groups>
+- <doc:upcoming-language-features>

userdocs/diagnostics/existential-any.md

@@ -1,24 +1,47 @@
-# `ExistentialAny`
+# Existential any (ExistentialAny)
 
-This diagnostic group includes errors and warnings pertaining to the `any` type
-syntax.
+`any` existential type syntax.
 
-This syntax was proposed in [SE-0335](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0335-existential-any.md).
-`any` syntax draws a line between constraint types and existential or boxed
-types.
 
-For example, `any Collection` is a boxed type abstracting over a value of a
-dynamic type that conforms to the protocol `Collection`, whereas the
-`Collection` part is the conformance constraint imposed on the type of the
-underlying value *as well as* a constraint type.
-The distinction between a conformance constraint and a constraint type can be
-clearly seen in classic generic syntax: `<T: Collection>`.
-
-Constraint types exist to express conformances and have no meaning in relation
-to values.
+## Overview
 
+`any` was introduced in Swift 5.6 to explicitly mark "existential types", i.e., abstract boxed types
+that conform to a set of constraints. For source compatibility, these are not diagnosed by default
+except for existential types constrained to protocols with `Self` or associated type requirements
+(as this was introduced in the same version):
 ```swift
-func sillyFunction(collection: Collection) { // error
-  // ...
+protocol Foo {
+  associatedtype Bar
+
+  func foo(_: Bar)
 }
+
+protocol Baz {}
+
+func pass(foo: Foo) {} // `any Foo` is required instead of `Foo`
+
+func pass(baz: Baz) {} // no warning or error by default for source compatibility
 ```
+
+When enabled via `-enable-upcoming-feature ExistentialAny`, the upcoming language feature
+`ExistentialAny` will diagnose *all* existential types without `any`:
+```swift
+func pass(baz: Baz) {} // `any Baz` required instead of `Baz`
+```
+
+This will become the default in a future language mode.
+
+
+## Migration
+
+```sh
+-enable-upcoming-feature ExistentialAny:migrate
+```
+
+Enabling migration for `ExistentialAny` adds fix-its that prepend all existential types with `any`
+as required. No attempt is made to convert to generic (`some`) types.
+
+
+## See Also
+
+- [SE-0335: Introduce existential `any`](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0335-existential-any.md)

userdocs/diagnostics/member-import-visibility.md

@@ -1,15 +1,36 @@
-# Member import visibility
+# Member import visibility (MemberImportVisibility)
 
+Enables errors for uses of members that cannot be accessed because their defining module is not directly
+imported.
 
-This diagnostic group includes the errors that are emitted when a member declaration cannot be accessed because the module defining that member has not been directly imported by the file containing the reference:
 
-```
+## Overview
+
+Prior to enabling this feature, it was possible to use a member if it was declared in a module that
+was transitively imported. `MemberImportVisibility` unifies the visibility rules for members to
+match those of top-level, such that only members contained in a direct import are visible:
+
+```swift
 func getFileContents() throws -> String {
   // error: initializer 'init(contentsOfFile:)' is not available due to missing import of defining module 'Foundation'
   return try String(contentsOfFile: "example.txt")
 }
 ```
 
-To resolve the error, you must add an import of the module that defines the member.
+To resolve the error, add an import of the module that defines the member.
+
+
+## Migration
+
+```sh
+-enable-upcoming-feature MemberImportVisibility:migrate
+```
+
+Enabling migration for `MemberImportVisibility` adds fix-its for the missing modules, i.e. those that
+declare members used in the file and are not directly imported.
+
+
+## See also
+
+- [SE-0444: Member import visibility](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0444-member-import-visibility.md)
 
-These errors are only emitted when the `MemberImportVisibility` language mode is enabled.

userdocs/diagnostics/nonisolated-nonsending-by-default.md

@@ -1,15 +1,74 @@
-# `NonisolatedNonsendingByDefault`
+# nonisolated(nonsending) by Default (NonisolatedNonsendingByDefault)
 
-This feature changes the behavior of nonisolated async
-functions to run on the actor to which the caller is isolated (if any) by 
-default, and provides an explicit way to express the execution semantics for
-these functions.
+Runs nonisolated async functions on the caller's actor by default.
 
-This feature was proposed in [SE-0461](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0461-async-function-isolation.md)
 
-* The `@concurrent` attribute specifies that a function must always 
-  switch off of an actor to run.
-  This is the default behavior without `NonisolatedNonsendingByDefault`.
-* The `nonisolated(nonsending)` modifier specifies that a function must always 
-  run on the caller's actor.
-  This is the default behavior with `NonisolatedNonsendingByDefault`.
+## Overview
+
+Prior to this feature, nonisolated async functions *never* run on an actor's executor and instead
+switch to global generic executor. The motivation was to prevent unnecessary serialization and
+contention for the actor by switching off of the actor to run the nonisolated async function, but
+this does  have a number of unfortunate consequences:
+1. `nonisolated` is difficult to understand
+2. Async functions that run on the caller's actor are difficult to express
+3. It's easy to write invalid async APIs
+4. It's difficult to write higher-order async APIs
+
+Introduced in Swift 6.2, `-enable-upcoming-feature NonisolatedNonsendingByDefault` changes the
+execution semantics of nonisolated async functions to always run on the caller's actor by default. A
+new `@concurrent` attribute can be added in order to specify that a function must *always* switch
+off of an actor to run.
+```swift
+struct S: Sendable {
+  func performSync() {}
+
+  // `nonisolated(nonsending)` is the default
+  func performAsync() async {}
+
+  @concurrent
+  func alwaysSwitch() async {}
+}
+
+actor MyActor {
+  let s: Sendable
+
+  func call() async {
+    s.performSync() // runs on actor's executor
+
+    await s.performAsync() // runs on actor's executor
+
+    s.alwaysSwitch() // switches to global generic executor
+  }
+}
+```
+
+A `nonisolated(nonsending)` modifier can also be used prior to enabling this upcoming feature in
+order to run on the caller's actor. To achieve the same semantics as above, `S` in this case would
+instead be:
+```swift
+struct S: Sendable {
+  func performSync() {}
+
+  nonisolated(nonsending)
+  func performAsync() async {}
+
+  // `@concurrent` is the default
+  func alwaysSwitch() async {}
+}
+```
+
+
+## Migration
+
+```sh
+-enable-upcoming-feature NonisolatedNonsendingByDefault:migrate
+```
+
+Enabling migration for `NonisolatedNonsendingByDefault` adds fix-its that aim to keep the current
+async semantics by adding `@concurrent` to all existing nonisolated async functions and closures.
+
+
+## See Also
+
+- [SE-0461: Run nonisolated async functions on the caller's actor by default](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0461-async-function-isolation.md)
+

userdocs/diagnostics/preconcurrency-import.md

@@ -1,6 +1,4 @@
-# Extraneous @preconcurrency imports
+# Extraneous @preconcurrency imports (PreconcurrencyImport)
 
-
-This diagnostic group includes warnings that diagnose `@preconcurrency import`
-declarations that don't need `@preconcurrency`. It is an experimental warning
-that is currently disabled.
+Warnings that diagnose `@preconcurrency import` declarations that don't need `@preconcurrency`,
+experimental and disabled by default.

userdocs/diagnostics/strict-language-features.md

@@ -1,8 +1,13 @@
-# Strict language feature enablement
-
-By default, if an unrecognized feature name is specified with the
-`-enable-upcoming-feature` or `-enable-experimental-feature` flags, the compiler
-will ignore it without emitting a diagnostic since some projects must be
-simultaneously compatible with multiple versions of the language and toolchain.
-However, this warning group can be enabled to opt-in to detailed diagnostics
-about misspecified features.
+# Strict language feature enablement (StrictLanguageFeatures)
+
+Warnings for unrecognized feature names in `-enable-upcoming-feature` or
+`enable-experimental-feature`.
+
+
+## Overview
+
+By default, if an unrecognized feature name is specified with the `-enable-upcoming-feature` or
+`-enable-experimental-feature` flags, the compiler will ignore it without emitting a diagnostic
+since some projects must be simultaneously compatible with multiple versions of the language and
+toolchain. This can, however, lead to misspecified features. To diagnose these cases instead, enable
+`StrictLanguageFeatures`.

userdocs/diagnostics/strict-memory-safety.md

@@ -1,7 +1,13 @@
-# Strict Memory Safety Warnings (`StrictMemorySafety`)
+# Strict memory safety (StrictMemorySafety)
 
+Warnings that identify the use of language constructs and library APIs that can undermine memory
+safety, disabled by default.
 
-This diagnostic group includes warnings that identify the use of language constructs and library APIs that can undermine memory safety. They are enabled by the `-strict-memory-safety` compiler flag. Examples of memory-unsafe code in Swift include:
+
+## Overview
+
+Strict memory safety can be enabled with the `-strict-memory-safety` compiler flag. Examples of
+memory-unsafe code in Swift include:
 
 - Use of a function or type annotated with `@unsafe`:
   ```swift
@@ -69,4 +75,4 @@ The warnings produced by strict memory safety can be suppressed by acknowledging
   @safe struct MyTemporaryBuffer<T> {
     private var storage: UnsafeBufferPointer<T>
   }
-  ```
+  ```

userdocs/diagnostics/unknown-warning-group.md

@@ -1,6 +1,9 @@
-# Unknown "Warning Group" Warnings (`UnknownWarningGroup`)
+# Unknown warning group (UnknownWarningGroup)
 
-The `UnknownWarningGroup` diagnostic group addresses warnings related to the specification of unrecognized warning groups in compilation flags.
+Warnings for unrecognized warning groups specified in `-Wwarning` or `-Werror`.
+
+
+## Overview
 
 ```sh
 swiftc -Werror non_existing_group file.swift