Merge pull request #85026 from bnbarham/user-doc-cleanup

Cleanup user docs

Author: bnbarham

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-descriptions.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/diagnostic-groups.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/diagnostics.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/dynamic-callable-requirements.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/error-in-future-swift-version.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/