Skip to content

Commit cf3bf78

Browse files
DougGregorDougGregor
authored
Merge pull request #80824 from DougGregor/diag-group-docs-on-swift-org-6.2
[6.2] Point at diagnostic group documentation on docs.swift.org
2 parents b5a61a1 + 31c6ed7 commit cf3bf78

7 files changed

+54
-36
lines changed

‎docs/Diagnostics.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ To add a new diagnostics group:
109109
- An entry in a `Diagnostics*.def` file describing the diagnostic. If there are any closely related diagnostics the note should also be attached to, they can usually be found nearby.
110110
- Each point in the compiler source where the diagnostic is emitted. This can be helpful in determining the exact circumstances which cause it to be emitted.
111111
4. Add a new Markdown file in the `userdocs/diagnostics/` directory in the swift repository containing the documentation. When writing a note, keep the writing guidelines from the section above in mind. The existing notes in the directory are another useful guide.
112-
5. Create a new entry in `DiagnosticGroups.def` that provides the name for your new diagnostic group along with the name of the file you added in step (4).
112+
5. Create a new entry in `DiagnosticGroups.def` that provides the name for your new diagnostic group along with the name of the file you added in step (4), without an extension.
113113
6. Find each diagnostic you want to make part of this group in the various `Diagnostics*.def` files. For each diagnostic, replace the `ERROR` or `WARNING` with `GROUPED_ERROR` or `GROUPED_WARNING`, respectively, and put the diagnostic group name after the string literal for the diagnostic message.
114114
7. If possible, rebuild the compiler and try recompiling your test program. Your new diagnostic group should appear as `[#<group name>]` at the end of the diagnostic, with a link to the diagnostic file.
115115
8. That's it! The new diagnostic group is now ready to be submitted as a pull request on GitHub.

‎include/swift/AST/DiagnosticGroups.def

Lines changed: 43 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,24 @@
1212
//
1313
// This file defines diagnostic groups and links between them.
1414
//
15+
// The GROUP(Name, Filename) macro is used to define each diagnostic group.
16+
// These groups are used to associate documentation with particular set of
17+
// diagnostics and also to provide more control over whether the warnings
18+
// in the group are escalated to errors (via the -Wwarning and -Werror flags.)
19+
// A given warning or error can be associated with a diagnostic group by using
20+
// GROUPED_WARNING or GROUPED_ERROR, respectively. New warnings and errors
21+
// should be introduced along with groups to improve documentation.
22+
//
23+
// - Name: the name of the group that will be shown in diagnostic messages
24+
// (e.g., StrictMemorySafety) and used in command-line options like
25+
// -Wwarning and -Werror. Once assigned, the group name for a particular
26+
// diagnostic should not be changed, because it will affect existing users
27+
// of the command-line flags.
28+
// - Filename: the name of the file that provides documentation for this
29+
// diagnostic group. There should be a corresponding Markdown file in
30+
// userdocs/diagnostics providing short-form documentation that helps
31+
// explain the diagnostic and how to resolve the problem.
32+
//
1533
//===----------------------------------------------------------------------===//
1634

1735
#define DEFINE_DIAGNOSTIC_GROUPS_MACROS
@@ -22,31 +40,31 @@
2240

2341
GROUP(no_group, "")
2442

25-
GROUP(ActorIsolatedCall, "actor-isolated-call.md")
26-
GROUP(AsyncCallerExecution, "async-caller-execution.md")
27-
GROUP(ConformanceIsolation, "conformance-isolation.md")
28-
GROUP(DeprecatedDeclaration, "deprecated-declaration.md")
29-
GROUP(DynamicCallable, "dynamic-callable-requirements.md")
30-
GROUP(ErrorInFutureSwiftVersion, "error-in-future-swift-version.md")
31-
GROUP(ExistentialAny, "existential-any.md")
32-
GROUP(ExistentialMemberAccess, "existential-member-access-limitations.md")
33-
GROUP(IsolatedConformances, "isolated-conformances.md")
34-
GROUP(MultipleInheritance, "multiple-inheritance.md")
35-
GROUP(MutableGlobalVariable, "mutable-global-variable.md")
36-
GROUP(NominalTypes, "nominal-types.md")
37-
GROUP(OpaqueTypeInference, "opaque-type-inference.md")
38-
GROUP(PreconcurrencyImport, "preconcurrency-import.md")
39-
GROUP(PropertyWrappers, "property-wrapper-requirements.md")
40-
GROUP(ProtocolTypeNonConformance, "protocol-type-non-conformance.md")
41-
GROUP(ResultBuilderMethods, "result-builder-methods.md")
42-
GROUP(SendableClosureCaptures, "sendable-closure-captures.md")
43-
GROUP(SendingRisksDataRace, "sending-risks-data-race.md")
44-
GROUP(StrictLanguageFeatures, "strict-language-features.md")
45-
GROUP(StrictMemorySafety, "strict-memory-safety.md")
46-
GROUP(StringInterpolationConformance, "string-interpolation-conformance.md")
47-
GROUP(TemporaryPointers, "temporary-pointers.md")
48-
GROUP(TrailingClosureMatching, "trailing-closure-matching.md")
49-
GROUP(UnknownWarningGroup, "unknown-warning-group.md")
43+
GROUP(ActorIsolatedCall, "actor-isolated-call")
44+
GROUP(AsyncCallerExecution, "async-caller-execution")
45+
GROUP(ConformanceIsolation, "conformance-isolation")
46+
GROUP(DeprecatedDeclaration, "deprecated-declaration")
47+
GROUP(DynamicCallable, "dynamic-callable-requirements")
48+
GROUP(ErrorInFutureSwiftVersion, "error-in-future-swift-version")
49+
GROUP(ExistentialAny, "existential-any")
50+
GROUP(ExistentialMemberAccess, "existential-member-access-limitations")
51+
GROUP(IsolatedConformances, "isolated-conformances")
52+
GROUP(MultipleInheritance, "multiple-inheritance")
53+
GROUP(MutableGlobalVariable, "mutable-global-variable")
54+
GROUP(NominalTypes, "nominal-types")
55+
GROUP(OpaqueTypeInference, "opaque-type-inference")
56+
GROUP(PreconcurrencyImport, "preconcurrency-import")
57+
GROUP(PropertyWrappers, "property-wrapper-requirements")
58+
GROUP(ProtocolTypeNonConformance, "protocol-type-non-conformance")
59+
GROUP(ResultBuilderMethods, "result-builder-methods")
60+
GROUP(SendableClosureCaptures, "sendable-closure-captures")
61+
GROUP(SendingRisksDataRace, "sending-risks-data-race")
62+
GROUP(StrictLanguageFeatures, "strict-language-features")
63+
GROUP(StrictMemorySafety, "strict-memory-safety")
64+
GROUP(StringInterpolationConformance, "string-interpolation-conformance")
65+
GROUP(TemporaryPointers, "temporary-pointers")
66+
GROUP(TrailingClosureMatching, "trailing-closure-matching")
67+
GROUP(UnknownWarningGroup, "unknown-warning-group")
5068

5169
#define UNDEFINE_DIAGNOSTIC_GROUPS_MACROS
5270
#include "swift/AST/DefineDiagnosticGroupsMacros.h"

‎lib/Frontend/CompilerInvocation.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2636,7 +2636,7 @@ static void configureDiagnosticEngine(
26362636
std::string docsPath = Options.DiagnosticDocumentationPath;
26372637
if (docsPath.empty()) {
26382638
// Point at the latest Markdown documentation on GitHub.
2639-
docsPath = "https://github.com/swiftlang/swift/tree/main/userdocs/diagnostics";
2639+
docsPath = "https://docs.swift.org/compiler/documentation/diagnostics";
26402640
}
26412641
Diagnostics.setDiagnosticDocumentationPath(docsPath);
26422642

‎test/SourceKit/Sema/educational_note_diags.swift

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,13 @@ extension Crap {}
55

66
// NO_OVERRIDE: key.description: "non-nominal type
77
// NO_OVERRIDE: key.educational_note_paths: [
8-
// NO_OVERRIDE-NEXT: share{{[/\\]+}}doc{{[/\\]+}}swift{{[/\\]+}}diagnostics{{[/\\]+}}nominal-types.md"
8+
// NO_OVERRIDE-NEXT: share{{[/\\]+}}doc{{[/\\]+}}swift{{[/\\]+}}diagnostics{{[/\\]+}}nominal-types"
99
// NO_OVERRIDE-NEXT: ]
1010

1111
// RUN: %sourcekitd-test -req=sema %s -- -Xfrontend -diagnostic-documentation-path -Xfrontend /educational/notes/path/prefix %s | %FileCheck %s -check-prefix=OVERRIDE
1212

1313
// OVERRIDE: key.description: "non-nominal type
1414
// OVERRIDE: key.educational_note_paths: [
15-
// OVERRIDE-NEXT: "{{[/\\]+}}educational{{[/\\]+}}notes{{[/\\]+}}path{{[/\\]+}}prefix{{[/\\]+}}nominal-types.md"
15+
// OVERRIDE-NEXT: "{{[/\\]+}}educational{{[/\\]+}}notes{{[/\\]+}}path{{[/\\]+}}prefix{{[/\\]+}}nominal-types"
1616
// OVERRIDE-NEXT: ]
1717

‎test/diagnostics/diagnostic-group-serialization.swift

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ func f() { }
1010

1111
func g() {
1212
f()
13-
// CHECK: [[@LINE-1]]:3: warning: 'f()' is deprecated: please do not use [-W{{.*}}deprecated-declaration.md] [DeprecatedDeclaration]
13+
// CHECK: [[@LINE-1]]:3: warning: 'f()' is deprecated: please do not use [-W{{.*}}deprecated-declaration] [DeprecatedDeclaration]
1414
}
1515

1616

@@ -19,7 +19,7 @@ func beCareful() { }
1919

2020
func test() {
2121
beCareful()
22-
// CHECK: [[@LINE-1]]:3: warning: expression uses unsafe constructs but is not marked with 'unsafe' [-W{{.*}}strict-memory-safety.md] [StrictMemorySafety]
22+
// CHECK: [[@LINE-1]]:3: warning: expression uses unsafe constructs but is not marked with 'unsafe' [-W{{.*}}strict-memory-safety] [StrictMemorySafety]
2323
}
2424

25-
// CHECK: [StrictMemorySafety]: <{{.*}}strict-memory-safety.md>
25+
// CHECK: [StrictMemorySafety]: <{{.*}}strict-memory-safety>

‎test/diagnostics/educational_notes_serialization.swift

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,13 @@
77

88
typealias Fn = () -> ()
99
extension Fn {}
10-
// CHECK: [[@LINE-1]]:1: error: non-nominal type 'Fn' (aka '() -> ()') cannot be extended [{{.*}}nominal-types.md] [NominalTypes]
10+
// CHECK: [[@LINE-1]]:1: error: non-nominal type 'Fn' (aka '() -> ()') cannot be extended [{{.*}}nominal-types] [NominalTypes]
1111

1212

1313
// Shares the flag record with `Fn`
1414
typealias Dup = () -> ()
1515
extension Dup {}
16-
// CHECK: [[@LINE-1]]:1: error: non-nominal type 'Dup' (aka '() -> ()') cannot be extended [{{.*}}nominal-types.md] [NominalTypes]
16+
// CHECK: [[@LINE-1]]:1: error: non-nominal type 'Dup' (aka '() -> ()') cannot be extended [{{.*}}nominal-types] [NominalTypes]
1717

1818
do {
1919
func noNote(_: Int) {}

‎test/diagnostics/print-diagnostic-groups.swift

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
// RUN: %target-swift-frontend -typecheck %s 2>&1 | %FileCheck %s --check-prefix=CHECK-FILE -check-prefix CHECK
2-
// RUN: %target-swift-frontend -typecheck %s -diagnostic-documentation-path https://www.swift.org/documentation/compiler/diagnostics/ 2>&1 | %FileCheck %s --check-prefix=CHECK-HTTPS -check-prefix CHECK
2+
// RUN: %target-swift-frontend -typecheck %s -diagnostic-documentation-path https://docs.swift.org/compiler/documentation/diagnostics/ 2>&1 | %FileCheck %s --check-prefix=CHECK-HTTPS -check-prefix CHECK
33
// REQUIRES: swift_swift_parser
44

55
// CHECK: warning: file 'print-diagnostic-groups.swift' is part of module 'main'; ignoring import{{$}}
@@ -16,4 +16,4 @@ bar()
1616

1717
// CHECK-FILE: [#DeprecatedDeclarations]: <file://{{.*}}deprecated-declaration.md>
1818

19-
// CHECK-HTTPS: [#DeprecatedDeclaration]: <https://www.swift.org/documentation/compiler/diagnostics/deprecated-declaration.md>
19+
// CHECK-HTTPS: [#DeprecatedDeclaration]: <https://docs.swift.org/compiler/documentation/diagnostics/deprecated-declaration>

0 commit comments

Comments
 (0)