Skip to content

Commit 00ab365

Browse files
bnbarhambnbarham
committed
Add groupings for the various diagnostics
Also make the titles and one line summaries a little more consistent (at least for diagnsotic groups and upcoming language features, haven't gone through the educational notes).
1 parent 6e91fa8 commit 00ab365

9 files changed

+210
-60
lines changed

‎userdocs/diagnostics/clang-declaration-import.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
1-
# Imported Clang Declaration Warnings (`ClangDeclarationImport`)
1+
# Imported Clang declaration warnings (ClangDeclarationImport)
22

3-
4-
This diagnostic group covers all warnings related to malformed APIs that are imported into Swift from C, C++, and Obj-C headers.
3+
Covers all warnings related to malformed APIs that are imported into Swift from C, C++, and Obj-C headers.
54

65
As one example of a potential malformed API diagnostic, suppose a Clang module dependency contained the following declaration:
76

‎userdocs/diagnostics/deprecated-declaration.md

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
1-
# Deprecated Declaration Warnings (`DeprecatedDeclaration`)
1+
# Deprecated declaration warnings (DeprecatedDeclaration)
22

3-
4-
This diagnostic group includes warnings related to deprecated APIs that may be removed in future versions and should be replaced with more current alternatives.
3+
Warnings related to deprecated APIs that may be removed in future versions and should be replaced with more current alternatives.
54

65
The `DeprecatedDeclaration` group covers the following warnings:
76
- Use of a function annotated with `@available(<platform>, deprecated: <version>)`
@@ -65,10 +64,3 @@ The `DeprecatedDeclaration` group covers the following warnings:
6564
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
6665
}
6766
```
68-
69-
## Usage Example
70-
71-
```sh
72-
swiftc -Werror DeprecatedDeclaration file.swift
73-
swiftc -warnings-as-errors -Wwarning DeprecatedDeclaration file.swift
74-
```

‎userdocs/diagnostics/diagnostics.md

Lines changed: 81 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,84 @@
44
@TechnologyRoot
55
}
66

7-
Documentation on diagnostics emitted by the compiler.
7+
Documentation on diagnostics emitted by the compiler and settings that control them.
8+
9+
10+
## Diagnostics
11+
12+
Swift diagnostics are classified into errors and warnings. Warnings can only be silenced in an
13+
intentional manner, e.g., adding `_ =` for an unused function result.
14+
15+
Some diagnostics have extra documentation. These include a `[#Name]` inline and reference to this
16+
documentation at the end of the compiler output on the command line, or is presented specially
17+
within your IDE of choice. See below for the full list of these notes.
18+
19+
20+
## Diagnostic groups
21+
22+
Diagnostic groups collect some number of diagnostics together under a common group name. This allows
23+
for extra documentation (see the list below) to help explain relevant language concepts, as well as
24+
the ability to control the behavior of warnings in a more precise manner:
25+
- `-Werror <group>` - upgrades warnings in the specified group to errors
26+
- `-Wwarning <group>` - indicates that warnings in the specified group should remain warnings, even
27+
if they were previously upgraded to errors
28+
29+
As a concrete example, to upgrade deprecated declaration warnings to errors:
30+
```sh
31+
-Werror DeprecatedDeclaration
32+
```
33+
34+
Or upgrade all warnings except deprecated declaration to errors:
35+
```sh
36+
-warnings-as-errors -Wwarning DeprecatedDeclaration
37+
```
38+
39+
40+
## Upcoming language features
41+
42+
Upcoming language features allow for enabling features that will become the default in an upcoming
43+
language mode in your current language mode. This allows the incremental adoption of language
44+
features without having to fully migrate to a new language mode. They can be enabled on the command
45+
line with `-enable-upcoming-feature <feature>`.
46+
47+
48+
## Topics
49+
50+
### Diagnostics list
51+
52+
- <doc:actor-isolated-call>
53+
- <doc:conformance-isolation>
54+
- <doc:dynamic-callable-requirements>
55+
- <doc:error-in-future-swift-version>
56+
- <doc:existential-member-access-limitations>
57+
- <doc:isolated-conformances>
58+
- <doc:member-import-visibility>
59+
- <doc:multiple-inheritance>
60+
- <doc:mutable-global-variable>
61+
- <doc:nominal-types>
62+
- <doc:opaque-type-inference>
63+
- <doc:property-wrapper-requirements>
64+
- <doc:protocol-type-non-conformance>
65+
- <doc:result-builder-methods>
66+
- <doc:sendable-closure-captures>
67+
- <doc:sending-closure-risks-data-race>
68+
- <doc:sending-risks-data-race>
69+
- <doc:string-interpolation-conformance>
70+
- <doc:temporary-pointers>
71+
- <doc:trailing-closure-matching>
72+
73+
74+
### Diagnostic groups list
75+
76+
- <doc:clang-declaration-import>
77+
- <doc:deprecated-declaration>
78+
- <doc:preconcurrency-import>
79+
- <doc:strict-language-features>
80+
- <doc:strict-memory-safety>
81+
- <doc:unknown-warning-group>
82+
83+
84+
### Upcoming language features list
85+
86+
- <doc:existential-any>
87+
- <doc:nonisolated-nonsending-by-default>

‎userdocs/diagnostics/existential-any.md

Lines changed: 37 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,44 @@
1-
# `ExistentialAny`
1+
# Existential any (ExistentialAny)
22

3-
This diagnostic group includes errors and warnings pertaining to the `any` type
4-
syntax.
3+
`any` existential type syntax.
54

6-
This syntax was proposed in [SE-0335](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0335-existential-any.md).
7-
`any` syntax draws a line between constraint types and existential or boxed
8-
types.
5+
`any` was introduced in Swift 5.6 to explicitly mark "existential types", i.e., abstract boxed types
6+
that conform to a set of constraints. For source compatibility, these are not diagnosed by default
7+
except for existential types constrained to protocols with `Self` or associated type requirements
8+
(as this was introduced in the same version):
9+
```swift
10+
protocol Foo {
11+
associatedtype Bar
12+
13+
func foo(_: Bar)
14+
}
15+
16+
protocol Baz {}
917

10-
For example, `any Collection` is a boxed type abstracting over a value of a
11-
dynamic type that conforms to the protocol `Collection`, whereas the
12-
`Collection` part is the conformance constraint imposed on the type of the
13-
underlying value *as well as* a constraint type.
14-
The distinction between a conformance constraint and a constraint type can be
15-
clearly seen in classic generic syntax: `<T: Collection>`.
18+
func pass(foo: Foo) {} // `any Foo` is required instead of `Foo`
1619

17-
Constraint types exist to express conformances and have no meaning in relation
18-
to values.
20+
func pass(baz: Baz) {} // no warning or error by default for source compatibility
21+
```
1922

23+
When enabled via `-enable-upcoming-feature ExistentialAny`, the upcoming language feature
24+
`ExistentialAny` will diagnose *all* existential types without `any`:
2025
```swift
21-
func sillyFunction(collection: Collection) { // error
22-
// ...
23-
}
26+
func pass(baz: Baz) {} // `any Baz` required instead of `Baz`
2427
```
28+
29+
This will become the default in a future language mode.
30+
31+
32+
## Migration
33+
34+
```sh
35+
-enable-upcoming-feature ExistentialAny:migrate
36+
```
37+
38+
Migrating to `ExistentialAny` will prepend all existential types with `any` as required. No attempt
39+
is made to convert to generic (`some`) types.
40+
41+
42+
## See Also
43+
44+
- [SE-0335: Introduce existential `any`](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0335-existential-any.md)

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

Lines changed: 68 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,71 @@
1-
# `NonisolatedNonsendingByDefault`
1+
# nonisolated(nonsending) by Default (NonisolatedNonsendingByDefault)
22

3-
This feature changes the behavior of nonisolated async
4-
functions to run on the actor to which the caller is isolated (if any) by
5-
default, and provides an explicit way to express the execution semantics for
6-
these functions.
3+
Runs nonisolated async functions on the caller's actor by default.
74

8-
This feature was proposed in [SE-0461](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0461-async-function-isolation.md)
5+
Prior to this feature, nonisolated async functions *never* run on an actor's executor and instead
6+
switch to global generic executor. The motivation was to prevent unnecessary serialization and
7+
contention for the actor by switching off of the actor to run the nonisolated async function, but
8+
this does have a number of unfortunate consequences:
9+
1. `nonisolated` is difficult to understand
10+
2. Async functions that run on the caller's actor are difficult to express
11+
3. It's easy to write invalid async APIs
12+
4. It's difficult to write higher-order async APIs
13+
14+
Introduced in Swift 6.2, `-enable-upcoming-feature NonisolatedNonsendingByDefault` changes the
15+
execution semantics of nonisolated async functions to always run on the caller's actor by default. A
16+
new `@concurrent` attribute can be added in order to specify that a function must *always* switch
17+
off of an actor to run.
18+
```swift
19+
struct S: Sendable {
20+
func performSync() {}
21+
22+
// `nonisolated(nonsending)` is the default
23+
func performAsync() async {}
24+
25+
@concurrent
26+
func alwaysSwitch() async {}
27+
}
28+
29+
actor MyActor {
30+
let s: Sendable
31+
32+
func call() async {
33+
s.performSync() // runs on actor's executor
34+
35+
await s.performAsync() // runs on actor's executor
36+
37+
s.alwaysSwitch() // switches to global generic executor
38+
}
39+
}
40+
```
41+
42+
A `nonisolated(nonsending)` modifier can also be used prior to enabling this upcoming feature in
43+
order to run on the caller's actor. To achieve the same semantics as above, `S` in this case would
44+
instead be:
45+
```swift
46+
struct S: Sendable {
47+
func performSync() {}
48+
49+
nonisolated(nonsending)
50+
func performAsync() async {}
51+
52+
// `@concurrent` is the default
53+
func alwaysSwitch() async {}
54+
}
55+
```
56+
57+
58+
## Migration
59+
60+
```sh
61+
-enable-upcoming-feature NonisolatedNonsendingByDefault:migrate
62+
```
63+
64+
Migrating to `NonisolatedNonsendingByDefault` keeps the current async semantics by adding
65+
`@concurrent` to all existing nonisolated async functions and closures.
66+
67+
68+
## See Also
69+
70+
- [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)
971

10-
* The `@concurrent` attribute specifies that a function must always
11-
switch off of an actor to run.
12-
This is the default behavior without `NonisolatedNonsendingByDefault`.
13-
* The `nonisolated(nonsending)` modifier specifies that a function must always
14-
run on the caller's actor.
15-
This is the default behavior with `NonisolatedNonsendingByDefault`.

‎userdocs/diagnostics/preconcurrency-import.md

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,4 @@
1-
# Extraneous @preconcurrency imports
1+
# Extraneous @preconcurrency imports (PreconcurrencyImport)
22

3-
4-
This diagnostic group includes warnings that diagnose `@preconcurrency import`
5-
declarations that don't need `@preconcurrency`. It is an experimental warning
6-
that is currently disabled.
3+
Warnings that diagnose `@preconcurrency import` declarations that don't need `@preconcurrency`,
4+
experimental and disabled by default.

‎userdocs/diagnostics/strict-language-features.md

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1-
# Strict language feature enablement
1+
# Strict language feature enablement (StrictLanguageFeatures)
22

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

‎userdocs/diagnostics/strict-memory-safety.md

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
1-
# Strict Memory Safety Warnings (`StrictMemorySafety`)
1+
# Strict memory safety (StrictMemorySafety)
22

3+
Warnings that identify the use of language constructs and library APIs that can undermine memory
4+
safety, disabled by default.
35

4-
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:
6+
Strict memory safety can be enabled with the `-strict-memory-safety` compiler flag. Examples of
7+
memory-unsafe code in Swift include:
58

69
- Use of a function or type annotated with `@unsafe`:
710
```swift
@@ -69,4 +72,4 @@ The warnings produced by strict memory safety can be suppressed by acknowledging
6972
@safe struct MyTemporaryBuffer<T> {
7073
private var storage: UnsafeBufferPointer<T>
7174
}
72-
```
75+
```

‎userdocs/diagnostics/unknown-warning-group.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Unknown "Warning Group" Warnings (`UnknownWarningGroup`)
1+
# Unknown warning group (UnknownWarningGroup)
22

3-
The `UnknownWarningGroup` diagnostic group addresses warnings related to the specification of unrecognized warning groups in compilation flags.
3+
Warnings for unrecognized warning groups specified in `-Wwarning` or `-Werror`.
44

55
```sh
66
swiftc -Werror non_existing_group file.swift

0 commit comments

Comments
 (0)