[6.2] Point at diagnostic group documentation on docs.swift.org

docs/Diagnostics.md

@@ -109,7 +109,7 @@ To add a new diagnostics group:
     - 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.
     - 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.
 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.
-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).
+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.
 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.
 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.
 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

@@ -12,6 +12,24 @@
 //
 //  This file defines diagnostic groups and links between them.
 //
+//  The GROUP(Name, Filename) macro is used to define each diagnostic group.
+//  These groups are used to associate documentation with particular set of
+//  diagnostics and also to provide more control over whether the warnings
+//  in the group are escalated to errors (via the -Wwarning and -Werror flags.)
+//  A given warning or error can be associated with a diagnostic group by using
+//  GROUPED_WARNING or GROUPED_ERROR, respectively. New warnings and errors
+//  should be introduced along with groups to improve documentation.
+//
+//    - Name: the name of the group that will be shown in diagnostic messages
+//      (e.g., StrictMemorySafety) and used in command-line options like
+//      -Wwarning and -Werror. Once assigned, the group name for a particular
+//      diagnostic should not be changed, because it will affect existing users
+//      of the command-line flags.
+//    - Filename: the name of the file that provides documentation for this
+//      diagnostic group. There should be a corresponding Markdown file in
+//      userdocs/diagnostics providing short-form documentation that helps
+//      explain the diagnostic and how to resolve the problem.
+//
 //===----------------------------------------------------------------------===//
 
 #define DEFINE_DIAGNOSTIC_GROUPS_MACROS
@@ -22,31 +40,31 @@
 
 GROUP(no_group, "")
 
-GROUP(ActorIsolatedCall, "actor-isolated-call.md")
-GROUP(AsyncCallerExecution, "async-caller-execution.md")
-GROUP(ConformanceIsolation, "conformance-isolation.md")
-GROUP(DeprecatedDeclaration, "deprecated-declaration.md")
-GROUP(DynamicCallable, "dynamic-callable-requirements.md")
-GROUP(ErrorInFutureSwiftVersion, "error-in-future-swift-version.md")
-GROUP(ExistentialAny, "existential-any.md")
-GROUP(ExistentialMemberAccess, "existential-member-access-limitations.md")
-GROUP(IsolatedConformances, "isolated-conformances.md")
-GROUP(MultipleInheritance, "multiple-inheritance.md")
-GROUP(MutableGlobalVariable, "mutable-global-variable.md")
-GROUP(NominalTypes, "nominal-types.md")
-GROUP(OpaqueTypeInference, "opaque-type-inference.md")
-GROUP(PreconcurrencyImport, "preconcurrency-import.md")
-GROUP(PropertyWrappers, "property-wrapper-requirements.md")
-GROUP(ProtocolTypeNonConformance, "protocol-type-non-conformance.md")
-GROUP(ResultBuilderMethods, "result-builder-methods.md")
-GROUP(SendableClosureCaptures, "sendable-closure-captures.md")
-GROUP(SendingRisksDataRace, "sending-risks-data-race.md")
-GROUP(StrictLanguageFeatures, "strict-language-features.md")
-GROUP(StrictMemorySafety, "strict-memory-safety.md")
-GROUP(StringInterpolationConformance, "string-interpolation-conformance.md")
-GROUP(TemporaryPointers, "temporary-pointers.md")
-GROUP(TrailingClosureMatching, "trailing-closure-matching.md")
-GROUP(UnknownWarningGroup, "unknown-warning-group.md")
+GROUP(ActorIsolatedCall, "actor-isolated-call")
+GROUP(AsyncCallerExecution, "async-caller-execution")
+GROUP(ConformanceIsolation, "conformance-isolation")
+GROUP(DeprecatedDeclaration, "deprecated-declaration")
+GROUP(DynamicCallable, "dynamic-callable-requirements")
+GROUP(ErrorInFutureSwiftVersion, "error-in-future-swift-version")
+GROUP(ExistentialAny, "existential-any")
+GROUP(ExistentialMemberAccess, "existential-member-access-limitations")
+GROUP(IsolatedConformances, "isolated-conformances")
+GROUP(MultipleInheritance, "multiple-inheritance")
+GROUP(MutableGlobalVariable, "mutable-global-variable")
+GROUP(NominalTypes, "nominal-types")
+GROUP(OpaqueTypeInference, "opaque-type-inference")
+GROUP(PreconcurrencyImport, "preconcurrency-import")
+GROUP(PropertyWrappers, "property-wrapper-requirements")
+GROUP(ProtocolTypeNonConformance, "protocol-type-non-conformance")
+GROUP(ResultBuilderMethods, "result-builder-methods")
+GROUP(SendableClosureCaptures, "sendable-closure-captures")
+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")
 
 #define UNDEFINE_DIAGNOSTIC_GROUPS_MACROS
 #include "swift/AST/DefineDiagnosticGroupsMacros.h"

lib/Frontend/CompilerInvocation.cpp

@@ -2633,7 +2633,7 @@ static void configureDiagnosticEngine(
   std::string docsPath = Options.DiagnosticDocumentationPath;
   if (docsPath.empty()) {
     // Point at the latest Markdown documentation on GitHub.
-    docsPath = "https://github.com/swiftlang/swift/tree/main/userdocs/diagnostics";
+    docsPath = "https://docs.swift.org/compiler/documentation/diagnostics";
   }
   Diagnostics.setDiagnosticDocumentationPath(docsPath);
 

test/SourceKit/Sema/educational_note_diags.swift

@@ -5,13 +5,13 @@ extension Crap {}
 
 // NO_OVERRIDE:      key.description: "non-nominal type
 // NO_OVERRIDE:      key.educational_note_paths: [
-// NO_OVERRIDE-NEXT:   share{{[/\\]+}}doc{{[/\\]+}}swift{{[/\\]+}}diagnostics{{[/\\]+}}nominal-types.md"
+// NO_OVERRIDE-NEXT:   share{{[/\\]+}}doc{{[/\\]+}}swift{{[/\\]+}}diagnostics{{[/\\]+}}nominal-types"
 // NO_OVERRIDE-NEXT: ]
 
 // RUN: %sourcekitd-test -req=sema %s -- -Xfrontend -diagnostic-documentation-path -Xfrontend /educational/notes/path/prefix %s | %FileCheck %s -check-prefix=OVERRIDE
 
 // OVERRIDE:      key.description: "non-nominal type
 // OVERRIDE:      key.educational_note_paths: [
-// OVERRIDE-NEXT:   "{{[/\\]+}}educational{{[/\\]+}}notes{{[/\\]+}}path{{[/\\]+}}prefix{{[/\\]+}}nominal-types.md"
+// OVERRIDE-NEXT:   "{{[/\\]+}}educational{{[/\\]+}}notes{{[/\\]+}}path{{[/\\]+}}prefix{{[/\\]+}}nominal-types"
 // OVERRIDE-NEXT: ]
 

test/diagnostics/diagnostic-group-serialization.swift

@@ -10,7 +10,7 @@ func f() { }
 
 func g() {
   f()
-// CHECK: [[@LINE-1]]:3: warning: 'f()' is deprecated: please do not use [-W{{.*}}deprecated-declaration.md] [DeprecatedDeclaration]
+// CHECK: [[@LINE-1]]:3: warning: 'f()' is deprecated: please do not use [-W{{.*}}deprecated-declaration] [DeprecatedDeclaration]
 }
 
 
@@ -19,7 +19,7 @@ func beCareful() { }
 
 func test() {
   beCareful()
-// CHECK: [[@LINE-1]]:3: warning: expression uses unsafe constructs but is not marked with 'unsafe' [-W{{.*}}strict-memory-safety.md] [StrictMemorySafety]
+// CHECK: [[@LINE-1]]:3: warning: expression uses unsafe constructs but is not marked with 'unsafe' [-W{{.*}}strict-memory-safety] [StrictMemorySafety]
 }
 
-// CHECK: [StrictMemorySafety]: <{{.*}}strict-memory-safety.md>
+// CHECK: [StrictMemorySafety]: <{{.*}}strict-memory-safety>

test/diagnostics/educational_notes_serialization.swift

@@ -7,13 +7,13 @@
 
 typealias Fn = () -> ()
 extension Fn {}
-// CHECK: [[@LINE-1]]:1: error: non-nominal type 'Fn' (aka '() -> ()') cannot be extended [{{.*}}nominal-types.md] [NominalTypes]
+// CHECK: [[@LINE-1]]:1: error: non-nominal type 'Fn' (aka '() -> ()') cannot be extended [{{.*}}nominal-types] [NominalTypes]
 
 
 // Shares the flag record with `Fn`
 typealias Dup = () -> ()
 extension Dup {}
-// CHECK: [[@LINE-1]]:1: error: non-nominal type 'Dup' (aka '() -> ()') cannot be extended [{{.*}}nominal-types.md] [NominalTypes]
+// CHECK: [[@LINE-1]]:1: error: non-nominal type 'Dup' (aka '() -> ()') cannot be extended [{{.*}}nominal-types] [NominalTypes]
 
 do {
   func noNote(_: Int) {}

test/diagnostics/print-diagnostic-groups.swift

@@ -1,5 +1,5 @@
 // RUN: %target-swift-frontend -typecheck %s 2>&1 | %FileCheck %s --check-prefix=CHECK-FILE -check-prefix CHECK
-// 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
+// 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
 // REQUIRES: swift_swift_parser
 
 // CHECK: warning: file 'print-diagnostic-groups.swift' is part of module 'main'; ignoring import{{$}}
@@ -16,4 +16,4 @@ bar()
 
 // CHECK-FILE: [#DeprecatedDeclarations]: <file://{{.*}}deprecated-declaration.md>
 
-// CHECK-HTTPS: [#DeprecatedDeclaration]: <https://www.swift.org/documentation/compiler/diagnostics/deprecated-declaration.md>
+// CHECK-HTTPS: [#DeprecatedDeclaration]: <https://docs.swift.org/compiler/documentation/diagnostics/deprecated-declaration>