Revert "[Diagnostics] Introduce "Educational Notes" for diagnostics"

CMakeLists.txt

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

docs/Diagnostics.md

@@ -90,25 +90,6 @@ The Swift compiler has a setting (under LangOptions) called `DiagnosticsEditorMo
 
 Most diagnostics have no reason to change behavior under editor mode. An example of an exception is the "protocol requirements not satisfied diagnostic"; on the command line, it may be better to show all unsatisfied requirements, while in an IDE a single multi-line fix-it would be preferred.
 
-### Educational Notes ###
-
-**Note**: This feature is currently experimental. It can be enabled by passing the `-Xfrontend -enable-descriptive-diagnostics` flag.
-
-Educational notes are small snippets of documentation attached to a diagnostic which explain relevant language concepts. They are intended to further Swift's goal of progressive disclosure by providing a learning resource at the point of use for users encountering a new error message for the first time. In very limited circumstances, they also allow the main diagnostic message to use more precise and correct terminology (e.g. nominal types) which would otherwise be too unfriendly for beginners.
-
-When outputting diagnostics on the command line, educational notes will be printed after the main diagnostic body if descriptive diagnostics are enabled. When presented in an IDE, it's expected they will be collapsed under a disclosure arrow, info button, or similar to avoid cluttering output.
-
-Generally speaking, a diagnostic should try to provide educational notes for any concepts/terminology which is difficult to understand from context or is especially subtle. Educational notes should:
-- Explain a single language concept. This makes them easy to reuse across diagnostics and helps keep them clear, concise, and easy to understand.
-- Be written in unabbreviated English. These are longer form messages compared to the main diagnostic, so there is no need to omit needless words and punctuation.
-- Not generally exceed 3-4 paragraphs. Educational notes should be clear and easily digestible. Messages which are too long also have the potential to create diagnostics UX issues in some contexts.
-- Be accessible. Educational notes should be beginner friendly and avoid assuming unnecesary prior knowledge. The goal is not only to help users understand what a diagnostic is telling them, but also to turn errors and warnings into "teachable moments".
-- Include references to relevant chapters of _The Swift Programming Language_ if applicable.
-- Be written in Markdown, but avoid excessive markup to avoid impacting the terminal UX. 
-
-To add a new educational note:
-1. Add a new Markdown file in the `userdocs/diagnostics/` directory containing the contents of the note. 
-2. Associate the note with one or more diagnostics in EducationalNotes.def.
 
 ### Format Specifiers ###
 

include/swift/AST/DiagnosticConsumer.h

@@ -57,9 +57,6 @@ 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,9 +673,6 @@ 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;
@@ -726,13 +723,6 @@ 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/Basic/DiagnosticOptions.h

@@ -59,8 +59,6 @@ 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,10 +115,6 @@ 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,18 +116,6 @@ 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);
@@ -963,19 +951,6 @@ 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,13 +44,6 @@ 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
@@ -691,9 +684,7 @@ 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,8 +319,6 @@ 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,10 +69,6 @@ void PrintingDiagnosticConsumer::handleDiagnostic(SourceManager &SM,
     return;
 
   printDiagnostic(SM, Info);
-  for (auto path : Info.EducationalNotePaths) {
-    if (auto buffer = SM.getFileSystem()->getBufferForFile(path))
-      Stream << buffer->get()->getBuffer() << "\n";
-  }
 
   for (auto ChildInfo : Info.ChildDiagnosticInfo) {
     printDiagnostic(SM, *ChildInfo);