[Diagnostics] Reference markdown files for educational notes and diagnostic group documentation

include/swift/Bridging/ASTGen.h

@@ -28,6 +28,9 @@ void swift_ASTGen_addQueuedSourceFile(
 void swift_ASTGen_addQueuedDiagnostic(
     void *_Nonnull queued, const char *_Nonnull text, ptrdiff_t textLength,
     BridgedDiagnosticSeverity severity, const void *_Nullable sourceLoc,
+    const char *_Nullable categoryName, ptrdiff_t categoryNameLength,
+    const char *_Nullable documentationPath,
+    ptrdiff_t documentationPathLength,
     const void *_Nullable *_Nullable highlightRanges,
     ptrdiff_t numHighlightRanges);
 void swift_ASTGen_renderQueuedDiagnostics(

lib/AST/DiagnosticBridge.cpp

@@ -64,9 +64,17 @@ static void addQueueDiagnostic(void *queuedDiagnostics,
     highlightRanges.push_back(range.getEnd().getOpaquePointerValue());
   }
 
+  StringRef documentationPath;
+  if (info.EducationalNotePaths.size() > 0)
+    documentationPath = info.EducationalNotePaths[0];
+
   // FIXME: Translate Fix-Its.
   swift_ASTGen_addQueuedDiagnostic(queuedDiagnostics, text.data(), text.size(),
                                    severity, info.Loc.getOpaquePointerValue(),
+                                   info.Category.data(),
+                                   info.Category.size(),
+                                   documentationPath.data(),
+                                   documentationPath.size(),
                                    highlightRanges.data(),
                                    highlightRanges.size() / 2);
 }

lib/AST/DiagnosticEngine.cpp

@@ -1337,6 +1337,7 @@ DiagnosticEngine::diagnosticInfoForDiagnostic(const Diagnostic &diagnostic,
 
   auto groupID = diagnostic.getGroupID();
   StringRef Category;
+  const char * const *associatedNotes = nullptr;
   if (isAPIDigesterBreakageDiagnostic(diagnostic.getID()))
     Category = "api-digester-breaking-change";
   else if (isNoUsageDiagnostic(diagnostic.getID()))
@@ -1345,6 +1346,10 @@ DiagnosticEngine::diagnosticInfoForDiagnostic(const Diagnostic &diagnostic,
     Category = getDiagGroupInfoByID(groupID).name;
   else if (isDeprecationDiagnostic(diagnostic.getID()))
     Category = "deprecation";
+  else if ((associatedNotes = educationalNotes[(uint32_t)diagnostic.getID()]) &&
+           *associatedNotes) {
+    Category = llvm::sys::path::stem(*associatedNotes);
+  }
 
   auto fixIts = diagnostic.getFixIts();
   if (loc.isValid()) {

lib/ASTGen/Sources/ASTGen/DiagnosticsBridge.swift

@@ -165,6 +165,8 @@ fileprivate struct SimpleDiagnostic: DiagnosticMessage {
 
   let severity: DiagnosticSeverity
 
+  let category: DiagnosticCategory?
+
   var diagnosticID: MessageID {
     .init(domain: "SwiftCompiler", id: "SimpleDiagnostic")
   }
@@ -237,6 +239,10 @@ public func addQueuedDiagnostic(
   textLength: Int,
   severity: BridgedDiagnosticSeverity,
   cLoc: BridgedSourceLoc,
+  categoryName: UnsafePointer<UInt8>?,
+  categoryLength: Int,
+  documentationPath: UnsafePointer<UInt8>?,
+  documentationPathLength: Int,
   highlightRangesPtr: UnsafePointer<BridgedSourceLoc>?,
   numHighlightRanges: Int
 ) {
@@ -333,13 +339,43 @@ public func addQueuedDiagnostic(
     }
   }
 
+  let category: DiagnosticCategory? = categoryName.map { categoryNamePtr in
+    let categoryNameBuffer = UnsafeBufferPointer(
+      start: categoryNamePtr,
+      count: categoryLength
+    )
+    let categoryName = String(decoding: categoryNameBuffer, as: UTF8.self)
+
+    let documentationURL = documentationPath.map { documentationPathPtr in
+      let documentationPathBuffer = UnsafeBufferPointer(
+        start: documentationPathPtr,
+        count: documentationPathLength
+      )
+
+      let documentationPath = String(decoding: documentationPathBuffer, as: UTF8.self)
+
+      // If this looks doesn't look like a URL, prepend file://.
+      if !documentationPath.looksLikeURL {
+        return "file://\(documentationPath)"
+      }
+
+      return documentationPath
+    }
+
+    return DiagnosticCategory(
+      name: categoryName,
+      documentationURL: documentationURL
+    )
+  }
+
   let textBuffer = UnsafeBufferPointer(start: text, count: textLength)
   let diagnostic = Diagnostic(
     node: node,
     position: position,
     message: SimpleDiagnostic(
       message: String(decoding: textBuffer, as: UTF8.self),
-      severity: severity.asSeverity
+      severity: severity.asSeverity,
+      category: category
     ),
     highlights: highlights
   )
@@ -361,3 +397,30 @@ public func renderQueuedDiagnostics(
 
   renderedStringOutPtr.pointee = allocateBridgedString(renderedStr)
 }
+
+extension String {
+  /// Simple check to determine whether the string looks like the start of a
+  /// URL.
+  fileprivate var looksLikeURL: Bool {
+    var forwardSlashes: Int = 0
+    for c in self {
+      if c == "/" {
+        forwardSlashes += 1
+        if forwardSlashes > 2 {
+          return true
+        }
+
+        continue
+      }
+
+      if c.isLetter || c.isNumber {
+        forwardSlashes = 0
+        continue
+      }
+
+      return false
+    }
+
+    return false
+  }
+}

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] []
+// CHECK: [[@LINE-1]]:1: error: non-nominal type 'Fn' (aka '() -> ()') cannot be extended [{{.*}}nominal-types.md] [nominal-types]
 
 
 // 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] []
+// CHECK: [[@LINE-1]]:1: error: non-nominal type 'Dup' (aka '() -> ()') cannot be extended [{{.*}}nominal-types.md] [nominal-types]
 
 do {
   func noNote(_: Int) {}