Skip to content

Commit ccce10d

Browse files
DougGregorDougGregor
committed
Drop the ".md" suffix from diagnostic group file names in GROUP
While here, document the GROUP macro appropriately.
1 parent 88d6304 commit ccce10d

File tree

2 files changed

+44
-26
lines changed

2 files changed

+44
-26
lines changed

‎docs/Diagnostics.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ To add a new diagnostics group:
110110
- 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.
111111
- 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.
112112
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.
113-
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).
113+
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.
114114
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.
115115
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.
116116
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"

0 commit comments

Comments
 (0)