[Diagnostics] Introduce "Educational Notes" for diagnostics

Educational notes are small pieces of documentation which explain a concept
relevant to some diagnostic message. If -enable-descriptive-diagnostics is
passed, they will be printed after a diagnostic message if available.

Educational notes can be found at /usr/share/doc/diagnostics in a
toolchain, and are associated with specific compiler diagnostics in
EducationalNotes.def.

Author: owenv

CMakeLists.txt

@@ -1129,6 +1129,8 @@ endif()
 
 add_subdirectory(utils)
 
+add_subdirectory(userdocs)
+
 if ("${CMAKE_SYSTEM_NAME}" STREQUAL "Darwin")
   if(SWIFT_BUILD_PERF_TESTSUITE)
     add_subdirectory(benchmark)

include/swift/AST/DiagnosticConsumer.h

@@ -57,6 +57,9 @@ struct DiagnosticInfo {
   /// DiagnosticInfo of notes which are children of this diagnostic, if any
   ArrayRef<DiagnosticInfo *> ChildDiagnosticInfo;
 
+  /// Paths to "educational note" diagnostic documentation in the toolchain.
+  ArrayRef<std::string> EducationalNotePaths;
+
   /// Represents a fix-it, a replacement of one range of text with another.
   class FixIt {
     CharSourceRange Range;

include/swift/AST/DiagnosticEngine.h

@@ -673,6 +673,9 @@ namespace swift {
     /// Use descriptive diagnostic style when available.
     bool useDescriptiveDiagnostics = false;
 
+    /// Path to diagnostic documentation directory.
+    std::string diagnosticDocumentationPath = "";
+
     friend class InFlightDiagnostic;
     friend class DiagnosticTransaction;
     friend class CompoundDiagnosticTransaction;
@@ -723,6 +726,13 @@ namespace swift {
       return useDescriptiveDiagnostics;
     }
 
+    void setDiagnosticDocumentationPath(std::string path) {
+      diagnosticDocumentationPath = path;
+    }
+    StringRef getDiagnosticDocumentationPath() {
+      return diagnosticDocumentationPath;
+    }
+
     void ignoreDiagnostic(DiagID id) {
       state.setDiagnosticBehavior(id, DiagnosticState::Behavior::Ignore);
     }

include/swift/AST/EducationalNotes.def

@@ -0,0 +1,29 @@
+//===-- EducationalNotes.def - Diagnostic Documentation Content -*- C++ -*-===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2019 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+//
+// This file associates diagnostics with relevant educational notes which
+// explain important concepts.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef EDUCATIONAL_NOTES
+#  error Must define EDUCATIONAL_NOTES
+#endif
+
+// EDUCATIONAL_NOTES(DIAG_ID, EDUCATIONAL_NOTE_FILENAMES...)
+
+EDUCATIONAL_NOTES(non_nominal_no_initializers, "nominal-types.md")
+EDUCATIONAL_NOTES(non_nominal_extension, "nominal-types.md")
+EDUCATIONAL_NOTES(associated_type_witness_conform_impossible,
+                  "nominal-types.md")
+
+#undef EDUCATIONAL_NOTES

include/swift/Basic/DiagnosticOptions.h

@@ -59,6 +59,8 @@ class DiagnosticOptions {
   /// Descriptive diagnostic output is not intended to be machine-readable.
   bool EnableDescriptiveDiagnostics = false;
 
+  std::string DiagnosticDocumentationPath = "";
+
   /// Return a hash code of any components from these options that should
   /// contribute to a Swift Bridging PCH hash.
   llvm::hash_code getPCHHashComponents() const {

include/swift/Option/FrontendOptions.td

@@ -115,6 +115,10 @@ def show_diagnostics_after_fatal : Flag<["-"], "show-diagnostics-after-fatal">,
 
 def enable_descriptive_diagnostics : Flag<["-"], "enable-descriptive-diagnostics">,
   HelpText<"Show descriptive diagnostic information, if available.">;
+  
+def diagnostic_documentation_path
+  : Separate<["-"], "diagnostic-documentation-path">, MetaVarName<"<path>">,
+  HelpText<"Path to diagnostic documentation resources">;
 
 def enable_swiftcall : Flag<["-"], "enable-swiftcall">,
   HelpText<"Enable the use of LLVM swiftcall support">;

lib/AST/DiagnosticEngine.cpp

@@ -116,6 +116,18 @@ static constexpr const char *const fixItStrings[] = {
     "<not a fix-it>",
 };
 
+#define EDUCATIONAL_NOTES(DIAG, ...)                                           \
+  static constexpr const char *const DIAG##_educationalNotes[] = {__VA_ARGS__, \
+                                                                  nullptr};
+#include "swift/AST/EducationalNotes.def"
+
+static constexpr const char *const *educationalNotes[LocalDiagID::NumDiags]{
+    [LocalDiagID::invalid_diagnostic] = {},
+#define EDUCATIONAL_NOTES(DIAG, ...)                                           \
+  [LocalDiagID::DIAG] = DIAG##_educationalNotes,
+#include "swift/AST/EducationalNotes.def"
+};
+
 DiagnosticState::DiagnosticState() {
   // Initialize our per-diagnostic state to default
   perDiagnosticBehavior.resize(LocalDiagID::NumDiags, Behavior::Unspecified);
@@ -951,6 +963,19 @@ void DiagnosticEngine::emitDiagnostic(const Diagnostic &diagnostic) {
       }
     }
     info->ChildDiagnosticInfo = childInfoPtrs;
+    
+    SmallVector<std::string, 1> educationalNotePaths;
+    if (useDescriptiveDiagnostics) {
+      auto associatedNotes = educationalNotes[(uint32_t)diagnostic.getID()];
+      while (associatedNotes && *associatedNotes) {
+        SmallString<128> notePath(getDiagnosticDocumentationPath());
+        llvm::sys::path::append(notePath, *associatedNotes);
+        educationalNotePaths.push_back(notePath.str());
+        associatedNotes++;
+      }
+      info->EducationalNotePaths = educationalNotePaths;
+    }
+
     for (auto &consumer : Consumers) {
       consumer->handleDiagnostic(SourceMgr, *info);
     }

lib/Frontend/CompilerInvocation.cpp

@@ -44,6 +44,13 @@ void CompilerInvocation::setMainExecutablePath(StringRef Path) {
   llvm::sys::path::remove_filename(LibPath); // Remove /bin
   llvm::sys::path::append(LibPath, "lib", "swift");
   setRuntimeResourcePath(LibPath.str());
+
+  llvm::SmallString<128> DiagnosticDocsPath(Path);
+  llvm::sys::path::remove_filename(DiagnosticDocsPath); // Remove /swift
+  llvm::sys::path::remove_filename(DiagnosticDocsPath); // Remove /bin
+  llvm::sys::path::append(DiagnosticDocsPath, "share", "doc", "swift",
+                          "diagnostics");
+  DiagnosticOpts.DiagnosticDocumentationPath = DiagnosticDocsPath.str();
 }
 
 /// If we haven't explicitly passed -prebuilt-module-cache-path, set it to
@@ -682,7 +689,9 @@ static bool ParseDiagnosticArgs(DiagnosticOptions &Opts, ArgList &Args,
   Opts.PrintDiagnosticNames |= Args.hasArg(OPT_debug_diagnostic_names);
   Opts.EnableDescriptiveDiagnostics |=
       Args.hasArg(OPT_enable_descriptive_diagnostics);
-
+  if (Arg *A = Args.getLastArg(OPT_diagnostic_documentation_path)) {
+    Opts.DiagnosticDocumentationPath = A->getValue();
+  }
   assert(!(Opts.WarningsAsErrors && Opts.SuppressWarnings) &&
          "conflicting arguments; should have been caught by driver");
 

lib/Frontend/Frontend.cpp

@@ -319,6 +319,8 @@ void CompilerInstance::setUpDiagnosticOptions() {
   if (Invocation.getDiagnosticOptions().EnableDescriptiveDiagnostics) {
     Diagnostics.setUseDescriptiveDiagnostics(true);
   }
+  Diagnostics.setDiagnosticDocumentationPath(
+      Invocation.getDiagnosticOptions().DiagnosticDocumentationPath);
 }
 
 // The ordering of ModuleLoaders is important!

lib/Frontend/PrintingDiagnosticConsumer.cpp

@@ -69,6 +69,12 @@ void PrintingDiagnosticConsumer::handleDiagnostic(SourceManager &SM,
     return;
 
   printDiagnostic(SM, Info);
+  for (auto path : Info.EducationalNotePaths) {
+    auto buffer = llvm::MemoryBuffer::getFile(path);
+    if (buffer) {
+      Stream << buffer->get()->getBuffer() << "\n";
+    }
+  }
 
   for (auto ChildInfo : Info.ChildDiagnosticInfo) {
     printDiagnostic(SM, *ChildInfo);