[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);

test/diagnostics/educational-notes.swift

@@ -0,0 +1,15 @@
+// RUN: not %target-swift-frontend -enable-descriptive-diagnostics -diagnostic-documentation-path %S/test-docs/ -typecheck %s 2>&1 | %FileCheck %s
+
+// A diagnostic with no educational notes
+let x = 1 +
+// CHECK: error: expected expression after operator
+// CHECK-NOT: {{-+$}}
+
+// A diagnostic with an educational note
+extension (Int, Int) {}
+// CHECK: error: non-nominal type '(Int, Int)' cannot be extended
+// CHECK-NEXT: extension (Int, Int) {}
+// CHECK-NEXT: ^         ~~~~~~~~~~
+// CHECK-NEXT: Nominal Types
+// CHECK-NEXT: -------------
+// CHECK-NEXT: Nominal types documentation content

test/diagnostics/test-docs/nominal-types.md

@@ -0,0 +1,3 @@
+Nominal Types
+-------------
+Nominal types documentation content

userdocs/CMakeLists.txt

@@ -0,0 +1,3 @@
+swift_install_in_component(DIRECTORY diagnostics
+                           DESTINATION "share/doc/swift"
+                           COMPONENT compiler)

userdocs/diagnostics/nominal-types.md

@@ -0,0 +1,7 @@
+Nominal types
+-------------
+In Swift, a type is considered a nominal type if it is named.  In other words, it has been defined by declaring the type somewhere in code. Examples of nominal types include classes, structs and enums, all of which must be declared before using them. Nominal types are an important concept in Swift because they can be extended, explicitly initialized using the 'MyType()' syntax, and may conform to protocols.
+
+In contrast, non-nominal types have none of these capabilities. A non-nominal type is any type which is not nominal. They are sometimes called ”structural types” because they are usually obtained by composing other types. Examples include function types like '(Int) -> (String)', tuple types like '(Int, String)', metatypes like 'Int.Type', and special types like 'Any' and 'AnyObject'.
+
+Whether the name of a protocol refers to a nominal or non-nominal type depends on where it appears in code. When used in a declaration or extension like 'extension MyProtocol { … }', 'MyProtocol' refers to a protocol type, which is nominal. This means that it may be extended and conform to protocols. However, when written as the type of a constant or variable, MyProtocol instead refers to a non-nominal, existential type. As a result, code like 'let value: MyProtocol = MyProtocol()' is not allowed because 'MyProtocol' refers to a non-nominal type in this context and cannot be explicitly initialized.