[clang] splits diagnostic message into summary and reason

[cjdb]

Summary

Structured diagnostics enable us to have diagnostics that contain a headline
description and a detailed description. DiagReason represents the latter,
although some subengines might combine the two into a single message.

[cjdb]

Abandoning since we're going down a different design path now.

clang-tools-extra/clangd/Diagnostics.cpp

 
 namespace clang {
 namespace clangd {
 namespace {
 
 const char *getDiagnosticCode(unsigned ID) {
   switch (ID) {
 #define DIAG(ENUM, CLASS, DEFAULT_MAPPING, DESC, GROPU, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY, REASON)    \
   case clang::diag::ENUM:                                                      \
     return #ENUM;
 #include "clang/Basic/DiagnosticASTKinds.inc"
 #include "clang/Basic/DiagnosticAnalysisKinds.inc"
 #include "clang/Basic/DiagnosticCommentKinds.inc"
 #include "clang/Basic/DiagnosticCommonKinds.inc"
 #include "clang/Basic/DiagnosticDriverKinds.inc"
 #include "clang/Basic/DiagnosticFrontendKinds.inc"

clang/include/clang/Basic/Diagnostic.h

const FixItHint &getFixItHint(unsigned Idx) const {
     assert(Idx < getNumFixItHints() && "Invalid index!");
     return DiagObj->DiagStorage.FixItHints[Idx];
   }
 
   ArrayRef<FixItHint> getFixItHints() const {
     return DiagObj->DiagStorage.FixItHints;
   }
 
+  /// Format the summary into a string, substituting the
+  /// formal arguments into the %0 slots.
+  ///
+  /// The result is appended onto the \p OutStr array.
+  void FormatSummary(SmallVectorImpl<char> &OutStr) const;
+
+  /// Format the reason into a string, substituting the formal arguments into
+  /// the %0 slots.
+  ///
+  /// The result is appended onto the \p OutStr array.
+  void FormatReason(SmallVectorImpl<char> &OutStr) const;
+
   /// Format this diagnostic into a string, substituting the
   /// formal arguments into the %0 slots.
   ///
   /// The result is appended onto the \p OutStr array.
   void FormatDiagnostic(SmallVectorImpl<char> &OutStr) const;
 
   /// Format the given format-string into the output buffer using the
   /// arguments stored in this diagnostic.
   void FormatDiagnostic(const char *DiagStr, const char *DiagEnd,
                         SmallVectorImpl<char> &OutStr) const;
 };
 
 /**
  * Represents a diagnostic in a form that can be retained until its
  * corresponding source manager is destroyed.
  */
 class StoredDiagnostic {
   unsigned ID;
   DiagnosticsEngine::Level Level;
   FullSourceLoc Loc;
   std::string Message;
+  DiagnosticReason Reason;
+
   std::vector<CharSourceRange> Ranges;
   std::vector<FixItHint> FixIts;
 
 public:
   StoredDiagnostic() = default;
   StoredDiagnostic(DiagnosticsEngine::Level Level, const Diagnostic &Info);
   StoredDiagnostic(DiagnosticsEngine::Level Level, unsigned ID,
-                   StringRef Message);
+                   StringRef Message, DiagnosticReason Reason);
   StoredDiagnostic(DiagnosticsEngine::Level Level, unsigned ID,
-                   StringRef Message, FullSourceLoc Loc,
-                   ArrayRef<CharSourceRange> Ranges,
+                   StringRef Message, DiagnosticReason Reason,
+                   FullSourceLoc Loc, ArrayRef<CharSourceRange> Ranges,
                    ArrayRef<FixItHint> Fixits);
 
   /// Evaluates true when this object stores a diagnostic.
   explicit operator bool() const { return !Message.empty(); }
 
   unsigned getID() const { return ID; }
   DiagnosticsEngine::Level getLevel() const { return Level; }
   const FullSourceLoc &getLocation() const { return Loc; }
   StringRef getMessage() const { return Message; }
+  const DiagnosticReason &getReason() const { return Reason; }
 
   void setLocation(FullSourceLoc Loc) { this->Loc = Loc; }
 
   using range_iterator = std::vector<CharSourceRange>::const_iterator;
 
   range_iterator range_begin() const { return Ranges.begin(); }
   range_iterator range_end() const { return Ranges.end(); }
   unsigned range_size() const { return Ranges.size(); }

clang/include/clang/Basic/Diagnostic.td

 include "DiagnosticDocs.td"
 
 // This defines all of the named diagnostic categories.
 include "DiagnosticCategories.td"
 
 // This defines all of the named diagnostic groups.
 include "DiagnosticGroups.td"
 
+// Structured diagnostics enable us to have diagnostics that contain a headline
+// description and a detailed description. DiagReason represents the latter,
+// although some subengines might combine the two into a single message.
+class DiagReason<string value> {
+  string Value = value;
+}
+def NO_REASON_YET : DiagReason<"">;
 
 // All diagnostics emitted by the compiler are an indirect subclass of this.
-class Diagnostic<string summary, DiagClass DC, Severity defaultmapping> {
+class Diagnostic<string summary, DiagClass DC, Severity defaultmapping, DiagReason reason> {
   /// Component is specified by the file with a big let directive.
   string         Component = ?;
   string         Summary = summary;
   DiagClass      Class = DC;
   SFINAEResponse SFINAE = SFINAE_Suppress;
   bit            AccessControl = 0;
   bit            WarningNoWerror = 0;
   bit            ShowInSystemHeader = 0;
   bit            ShowInSystemMacro = 1;
   bit            Deferrable = 0;
   Severity       DefaultSeverity = defaultmapping;
   DiagGroup      Group;
   string         CategoryName = "";
+  DiagReason     Reason = reason;
 }
 
 class SFINAEFailure {
   SFINAEResponse SFINAE = SFINAE_SubstitutionFailure;
 }
 class NoSFINAE {
   SFINAEResponse SFINAE = SFINAE_Report;
 }
class Deferrable {
   bit Deferrable = 1;
 }
 
 class NonDeferrable {
   bit Deferrable = 0;
 }
 
 // FIXME: ExtWarn and Extension should also be SFINAEFailure by default.
-class Error<string str>     : Diagnostic<str, CLASS_ERROR, SEV_Error>, SFINAEFailure {
+class Error<string str, DiagReason reason = NO_REASON_YET>     : Diagnostic<str, CLASS_ERROR, SEV_Error, reason>, SFINAEFailure {
   bit ShowInSystemHeader = 1;
 }
 // Warnings default to on (but can be default-off'd with DefaultIgnore).
 // This is used for warnings about questionable code; warnings about
 // accepted language extensions should use Extension or ExtWarn below instead.
-class Warning<string str>   : Diagnostic<str, CLASS_WARNING, SEV_Warning>;
+class Warning<string str, DiagReason reason = NO_REASON_YET>   : Diagnostic<str, CLASS_WARNING, SEV_Warning, reason>;
 // Remarks can be turned on with -R flags and provide commentary, e.g. on
 // optimizer decisions.
-class Remark<string str>    : Diagnostic<str, CLASS_REMARK, SEV_Ignored>;
+class Remark<string str, DiagReason reason = NO_REASON_YET>    : Diagnostic<str, CLASS_REMARK, SEV_Ignored, reason>;
 // Extensions are warnings about accepted language extensions.
 // Extension warnings are default-off but enabled by -pedantic.
-class Extension<string str> : Diagnostic<str, CLASS_EXTENSION, SEV_Ignored>;
+class Extension<string str, DiagReason reason = NO_REASON_YET> : Diagnostic<str, CLASS_EXTENSION, SEV_Ignored, reason>;
 // ExtWarns are warnings about accepted language extensions.
 // ExtWarn warnings are default-on.
-class ExtWarn<string str>   : Diagnostic<str, CLASS_EXTENSION, SEV_Warning>;
+class ExtWarn<string str, DiagReason reason = NO_REASON_YET>   : Diagnostic<str, CLASS_EXTENSION, SEV_Warning, reason>;
 // Notes can provide supplementary information on errors, warnings, and remarks.
-class Note<string str>      : Diagnostic<str, CLASS_NOTE, SEV_Fatal/*ignored*/>;
+class Note<string str, DiagReason reason = NO_REASON_YET>      : Diagnostic<str, CLASS_NOTE, SEV_Fatal/*ignored*/, reason>;
 
 
 class DefaultIgnore { Severity DefaultSeverity = SEV_Ignored; }
 class DefaultWarn   { Severity DefaultSeverity = SEV_Warning; }
 class DefaultError  { Severity DefaultSeverity = SEV_Error; }
 class DefaultFatal  { Severity DefaultSeverity = SEV_Fatal; }
 class DefaultWarnNoWerror {
   bit WarningNoWerror = 1;

clang/include/clang/Basic/DiagnosticAST.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICAST_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY, REASON)    \
   ENUM,
 #define ASTSTART
 #include "clang/Basic/DiagnosticASTKinds.inc"
 #undef DIAG
   NUM_BUILTIN_AST_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICAST_H

clang/include/clang/Basic/DiagnosticAnalysis.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICANALYSIS_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY, REASON)    \
   ENUM,
 #define ANALYSISSTART
 #include "clang/Basic/DiagnosticAnalysisKinds.inc"
 #undef DIAG
   NUM_BUILTIN_ANALYSIS_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICANALYSIS_H

clang/include/clang/Basic/DiagnosticComment.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICCOMMENT_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY, REASON)    \
   ENUM,
 #define COMMENTSTART
 #include "clang/Basic/DiagnosticCommentKinds.inc"
 #undef DIAG
   NUM_BUILTIN_COMMENT_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICCOMMENT_H

clang/include/clang/Basic/DiagnosticCrossTU.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICCROSSTU_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY, REASON)    \
   ENUM,
 #define CROSSTUSTART
 #include "clang/Basic/DiagnosticCrossTUKinds.inc"
 #undef DIAG
   NUM_BUILTIN_CROSSTU_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICCROSSTU_H

clang/include/clang/Basic/DiagnosticDriver.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICDRIVER_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY, REASON)    \
   ENUM,
 #define DRIVERSTART
 #include "clang/Basic/DiagnosticDriverKinds.inc"
 #undef DIAG
   NUM_BUILTIN_DRIVER_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICDRIVER_H

clang/include/clang/Basic/DiagnosticFrontend.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICFRONTEND_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY, REASON)    \
   ENUM,
 #define FRONTENDSTART
 #include "clang/Basic/DiagnosticFrontendKinds.inc"
 #undef DIAG
   NUM_BUILTIN_FRONTEND_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICFRONTEND_H

clang/include/clang/Basic/DiagnosticIDs.h

namespace diag {
     class CustomDiagInfo;
 
     /// All of the diagnostics that can be emitted by the frontend.
     typedef unsigned kind;
 
     // Get typedefs for common diagnostics.
     enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, CATEGORY,      \
-             NOWERROR, SHOWINSYSHEADER, SHOWINSYSMACRO, DEFFERABLE)            \
+             NOWERROR, SHOWINSYSHEADER, SHOWINSYSMACRO, DEFFERABLE, REASON)    \
   ENUM,
 #define COMMONSTART
 #include "clang/Basic/DiagnosticCommonKinds.inc"
       NUM_BUILTIN_COMMON_DIAGNOSTICS
 #undef DIAG
     };
 
     /// Enum values that allow the client to map NOTEs, WARNINGs, and EXTENSIONs
static DiagnosticMapping deserialize(unsigned Bits) {
     Result.HasNoWarningAsError = (Bits >> 5) & 1;
     Result.HasNoErrorAsFatal = (Bits >> 4) & 1;
     Result.WasUpgradedFromWarning = (Bits >> 3) & 1;
     Result.Severity = Bits & 0x7;
     return Result;
   }
 };
 
+struct DiagnosticReason {
+  llvm::StringLiteral Value = "";
+
+  // FIXME(spaceship): default when C++20 becomes the default
+  bool operator==(const DiagnosticReason &Other) const { return Value == Other.Value; }
+  bool operator!=(const DiagnosticReason &Other) const { return !(*this == Other); }
+  bool operator<(const DiagnosticReason &Other) const { return Value < Other.Value; }
+  bool operator>(const DiagnosticReason &Other) const  { return Other < *this; }
+  bool operator<=(const DiagnosticReason &Other) const { return !(Other < *this); }
+  bool operator>=(const DiagnosticReason &Other) const { return !(*this < Other); }
+};
+
 /// Used for handling and querying diagnostic IDs.
 ///
 /// Can be used and shared by multiple Diagnostics for multiple translation units.
 class DiagnosticIDs : public RefCountedBase<DiagnosticIDs> {
 public:
   /// The level of the diagnostic, after it has been through mapping.
   enum Level {
     Ignored, Note, Remark, Warning, Error, Fatal
public:
   /// level.
   ///
   /// If this is the first request for this diagnostic, it is registered and
   /// created, otherwise the existing ID is returned.
 
   // FIXME: Replace this function with a create-only facilty like
   // createCustomDiagIDFromFormatString() to enforce safe usage. At the time of
   // writing, nearly all callers of this function were invalid.
-  unsigned getCustomDiagID(Level L, StringRef FormatString);
+  unsigned getCustomDiagID(Level L, StringRef FormatString,
+                           const DiagnosticReason &Reason = {});
 
   //===--------------------------------------------------------------------===//
   // Diagnostic classification and reporting interfaces.
   //
 
   /// Given a diagnostic ID, return a description of the issue.
   StringRef getDescription(unsigned DiagID) const;
 
+  /// Given a diagnostic ID, return the issue's reason.
+  StringRef getReason(unsigned DiagID) const;
+
   /// Return true if the unmapped diagnostic levelof the specified
   /// diagnostic ID is a Warning or Extension.
   ///
   /// This only works on builtin diagnostics, not custom ones, and is not
   /// legal to call on NOTEs.
   static bool isBuiltinWarningOrExtension(unsigned DiagID);
 
   /// Return true if the specified diagnostic is mapped to errors by

clang/include/clang/Basic/DiagnosticLex.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICLEX_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY, REASON)    \
   ENUM,
 #define LEXSTART
 #include "clang/Basic/DiagnosticLexKinds.inc"
 #undef DIAG
   NUM_BUILTIN_LEX_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICLEX_H

clang/include/clang/Basic/DiagnosticParse.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICPARSE_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY, REASON)    \
   ENUM,
 #define PARSESTART
 #include "clang/Basic/DiagnosticParseKinds.inc"
 #undef DIAG
   NUM_BUILTIN_PARSE_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICPARSE_H

clang/include/clang/Basic/DiagnosticRefactoring.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICREFACTORING_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY, REASON)    \
   ENUM,
 #define REFACTORINGSTART
 #include "clang/Basic/DiagnosticRefactoringKinds.inc"
 #undef DIAG
   NUM_BUILTIN_REFACTORING_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICREFACTORING_H

clang/include/clang/Basic/DiagnosticSema.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICSEMA_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY, REASON)    \
   ENUM,
 #define SEMASTART
 #include "clang/Basic/DiagnosticSemaKinds.inc"
 #undef DIAG
   NUM_BUILTIN_SEMA_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICSEMA_H

clang/include/clang/Basic/DiagnosticSemaKinds.td

 def note_ovl_candidate_illegal_constructor_adrspace_mismatch : Note<
     "candidate constructor ignored: cannot be used to construct an object "
     "in address space %0">;
 def note_ovl_candidate_bad_deduction : Note<
     "candidate template ignored: failed template argument deduction">;
 def note_ovl_candidate_incomplete_deduction : Note<"candidate template ignored: "
     "couldn't infer template argument %0">;
 def note_ovl_candidate_incomplete_deduction_pack : Note<
-    "candidate template ignored: "
-    "deduced too few arguments for expanded pack %0; no argument for %ordinal1 "
-    "expanded parameter in deduced argument pack %2">;
+    "candidate template ignored",
+    DiagReason<"deduced too few arguments for expanded pack %0; no argument for"
+               " %ordinal1 expanded parameter in deduced argument pack %2">>;
 def note_ovl_candidate_inconsistent_deduction : Note<
-    "candidate template ignored: deduced %select{conflicting types|"
-    "conflicting values|conflicting templates|packs of different lengths}0 "
-    "for parameter %1%diff{ ($ vs. $)|}2,3">;
+    "candidate template ignored",
+    DiagReason<"deduced %select{conflicting types|conflicting values|"
+               "conflicting templates|packs of different lengths}0 "
+    "for parameter %1%diff{ ($ vs. $)|}2,3">>;
 def note_ovl_candidate_inconsistent_deduction_types : Note<
-    "candidate template ignored: deduced values %diff{"
+    "candidate template ignored",
+    DiagReason<"deduced values %diff{"
       "of conflicting types for parameter %0 (%1 of type $ vs. %3 of type $)|"
-    "%1 and %3 of conflicting types for parameter %0}2,4">;
+      "%1 and %3 of conflicting types for parameter %0}2,4">>;
 def note_ovl_candidate_explicit_arg_mismatch_named : Note<
-    "candidate template ignored: invalid explicitly-specified argument "
-    "for template parameter %0">;
+    "candidate template ignored",
+    DiagReason<"invalid explicitly-specified argument for template parameter %0">>;
 def note_ovl_candidate_unsatisfied_constraints : Note<
-    "candidate template ignored: constraints not satisfied%0">;
+    "candidate template ignored",
+    DiagReason<"constraints not satisfied%0">>;
 def note_ovl_candidate_explicit_arg_mismatch_unnamed : Note<
-    "candidate template ignored: invalid explicitly-specified argument "
-    "for %ordinal0 template parameter">;
+    "candidate template ignored",
+    DiagReason<"invalid explicitly-specified argument for %ordinal0 template "
+               "parameter">>;
 def note_ovl_candidate_instantiation_depth : Note<
-    "candidate template ignored: substitution exceeded maximum template "
-    "instantiation depth">;
+    "candidate template ignored",
+    DiagReason<"substitution exceeded maximum template instantiation depth">>;
 def note_ovl_candidate_underqualified : Note<
-    "candidate template ignored: cannot deduce a type for %0 that would "
-    "make %2 equal %1">;
+    "candidate template ignored",
+    DiagReason<"cannot deduce a type for %0 that would make %2 equal %1">>;
 def note_ovl_candidate_substitution_failure : Note<
-    "candidate template ignored: substitution failure%0%1">;
+    "candidate template ignored",
+    DiagReason<"substitution failure%0%1">>;
 def note_ovl_candidate_disabled_by_enable_if : Note<
-    "candidate template ignored: disabled by %0%1">;
+    "candidate template ignored",
+    DiagReason<"disabled by %0%1">>;
 def note_ovl_candidate_disabled_by_requirement : Note<
-    "candidate template ignored: requirement '%0' was not satisfied%1">;
+    "candidate template ignored",
+    DiagReason<"requirement '%0' was not satisfied%1">>;
 def note_ovl_candidate_has_pass_object_size_params: Note<
     "candidate address cannot be taken because parameter %0 has "
     "pass_object_size attribute">;
 def err_diagnose_if_succeeded : Error<"%0">;
 def warn_diagnose_if_succeeded : Warning<"%0">, InGroup<UserDefinedWarnings>,
     ShowInSystemHeader;
 def note_ovl_candidate_disabled_by_function_cond_attr : Note<
     "candidate disabled: %0">;

clang/include/clang/Basic/DiagnosticSerialization.h

 #define LLVM_CLANG_BASIC_DIAGNOSTICSERIALIZATION_H
 
 #include "clang/Basic/Diagnostic.h"
 
 namespace clang {
 namespace diag {
 enum {
 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY, REASON)    \
   ENUM,
 #define SERIALIZATIONSTART
 #include "clang/Basic/DiagnosticSerializationKinds.inc"
 #undef DIAG
   NUM_BUILTIN_SERIALIZATION_DIAGNOSTICS
 };
 } // end namespace diag
 } // end namespace clang
 
 #endif // LLVM_CLANG_BASIC_DIAGNOSTICSERIALIZATION_H

clang/include/clang/Frontend/ASTUnit.h

struct StandaloneFixIt {
     std::string CodeToInsert;
     bool BeforePreviousInsertions;
   };
 
   struct StandaloneDiagnostic {
     unsigned ID;
     DiagnosticsEngine::Level Level;
     std::string Message;
+    DiagnosticReason Reason;
     std::string Filename;
     unsigned LocOffset;
     std::vector<std::pair<unsigned, unsigned>> Ranges;
     std::vector<StandaloneFixIt> FixIts;
   };
 
 private:
   std::shared_ptr<LangOptions>            LangOpts;

clang/lib/Basic/Diagnostic.cpp

static const char *getTokenDescForDiagnostic(tok::TokenKind Kind) {
   switch (Kind) {
   case tok::identifier:
     return "identifier";
   default:
     return nullptr;
   }
 }
 
-/// FormatDiagnostic - Format this diagnostic into a string, substituting the
-/// formal arguments into the %0 slots.  The result is appended onto the Str
-/// array.
-void Diagnostic::
-FormatDiagnostic(SmallVectorImpl<char> &OutStr) const {
+void Diagnostic::FormatSummary(SmallVectorImpl<char> &OutStr) const {
   if (!StoredDiagMessage.empty()) {
     OutStr.append(StoredDiagMessage.begin(), StoredDiagMessage.end());
     return;
   }
 
   StringRef Diag =
     getDiags()->getDiagnosticIDs()->getDescription(getID());
 
   FormatDiagnostic(Diag.begin(), Diag.end(), OutStr);
 }
 
+void Diagnostic::FormatReason(SmallVectorImpl<char> &OutStr) const {
+  StringRef Diag = getDiags()->getDiagnosticIDs()->getReason(getID());
+  if (!Diag.empty()) {
+    StringRef Colon = ": ";
+    OutStr.append(Colon.begin(), Colon.end());
+    FormatDiagnostic(Diag.begin(), Diag.end(), OutStr);
+  }
+}
+
+void Diagnostic::FormatDiagnostic(SmallVectorImpl<char> &OutStr) const {
+  FormatSummary(OutStr);
+  FormatReason(OutStr);
+}
+
 /// pushEscapedString - Append Str to the diagnostic buffer,
 /// escaping non-printable characters and ill-formed code unit sequences.
 static void pushEscapedString(StringRef Str, SmallVectorImpl<char> &OutStr) {
   OutStr.reserve(OutStr.size() + Str.size());
   auto *Begin = reinterpret_cast<const unsigned char *>(Str.data());
   llvm::raw_svector_ostream OutStream(OutStr);
   const unsigned char *End = Begin + Str.size();
   while (Begin != End) {
else
                                         (intptr_t)getArgStdStr(ArgNo).c_str()));
   }
 
   // Append the type tree to the end of the diagnostics.
   OutStr.append(Tree.begin(), Tree.end());
 }
 
 StoredDiagnostic::StoredDiagnostic(DiagnosticsEngine::Level Level, unsigned ID,
-                                   StringRef Message)
-    : ID(ID), Level(Level), Message(Message) {}
+                                   StringRef Message, DiagnosticReason Reason)
+    : ID(ID), Level(Level), Message(Message), Reason(std::move(Reason)) {}
 
 StoredDiagnostic::StoredDiagnostic(DiagnosticsEngine::Level Level,
                                    const Diagnostic &Info)
     : ID(Info.getID()), Level(Level) {
   assert((Info.getLocation().isInvalid() || Info.hasSourceManager()) &&
        "Valid source location without setting a source manager for diagnostic");
   if (Info.getLocation().isValid())
     Loc = FullSourceLoc(Info.getLocation(), Info.getSourceManager());
   SmallString<64> Message;
   Info.FormatDiagnostic(Message);
   this->Message.assign(Message.begin(), Message.end());
   this->Ranges.assign(Info.getRanges().begin(), Info.getRanges().end());
   this->FixIts.assign(Info.getFixItHints().begin(), Info.getFixItHints().end());
 }
 
 StoredDiagnostic::StoredDiagnostic(DiagnosticsEngine::Level Level, unsigned ID,
-                                   StringRef Message, FullSourceLoc Loc,
+                                   StringRef Message, DiagnosticReason Reason,
+                                   FullSourceLoc Loc,
                                    ArrayRef<CharSourceRange> Ranges,
                                    ArrayRef<FixItHint> FixIts)
-    : ID(ID), Level(Level), Loc(Loc), Message(Message),
-      Ranges(Ranges.begin(), Ranges.end()), FixIts(FixIts.begin(), FixIts.end())
-{
-}
+    : ID(ID), Level(Level), Loc(Loc), Message(Message), Reason(Reason),
+      Ranges(Ranges.begin(), Ranges.end()),
+      FixIts(FixIts.begin(), FixIts.end()) {}
 
 llvm::raw_ostream &clang::operator<<(llvm::raw_ostream &OS,
                                      const StoredDiagnostic &SD) {
   if (SD.getLocation().hasManager())
     OS << SD.getLocation().printToString(SD.getLocation().getManager()) << ": ";
   OS << SD.getMessage();
   return OS;
 }

clang/lib/Basic/DiagnosticIDs.cpp

 
 struct StaticDiagInfoRec;
 
 // Store the descriptions in a separate table to avoid pointers that need to
 // be relocated, and also decrease the amount of data needed on 64-bit
 // platforms. See "How To Write Shared Libraries" by Ulrich Drepper.
 struct StaticDiagInfoDescriptionStringTable {
 #define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY, REASON)    \
   char ENUM##_desc[sizeof(DESC)];
   // clang-format off
 #include "clang/Basic/DiagnosticCommonKinds.inc"
 #include "clang/Basic/DiagnosticDriverKinds.inc"
 #include "clang/Basic/DiagnosticFrontendKinds.inc"
 #include "clang/Basic/DiagnosticSerializationKinds.inc"
 #include "clang/Basic/DiagnosticLexKinds.inc"
 #include "clang/Basic/DiagnosticParseKinds.inc"
 #include "clang/Basic/DiagnosticASTKinds.inc"
 #include "clang/Basic/DiagnosticCommentKinds.inc"
 #include "clang/Basic/DiagnosticCrossTUKinds.inc"
 #include "clang/Basic/DiagnosticSemaKinds.inc"
 #include "clang/Basic/DiagnosticAnalysisKinds.inc"
 #include "clang/Basic/DiagnosticRefactoringKinds.inc"
   // clang-format on
 #undef DIAG
 };
 
 const StaticDiagInfoDescriptionStringTable StaticDiagInfoDescriptions = {
 #define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             REASON)                                      \
   DESC,
 // clang-format off
 #include "clang/Basic/DiagnosticCommonKinds.inc"
 #include "clang/Basic/DiagnosticDriverKinds.inc"
 #include "clang/Basic/DiagnosticFrontendKinds.inc"
 #include "clang/Basic/DiagnosticSerializationKinds.inc"
 #include "clang/Basic/DiagnosticLexKinds.inc"
 #include "clang/Basic/DiagnosticParseKinds.inc"
 #include "clang/Basic/DiagnosticASTKinds.inc"
 #include "clang/Basic/DiagnosticCommentKinds.inc"
 #include "clang/Basic/DiagnosticCrossTUKinds.inc"
 #include "clang/Basic/DiagnosticSemaKinds.inc"
 #include "clang/Basic/DiagnosticAnalysisKinds.inc"
 #include "clang/Basic/DiagnosticRefactoringKinds.inc"
-  // clang-format on
 #undef DIAG
 };
 
 extern const StaticDiagInfoRec StaticDiagInfo[];
 
 // Stored separately from StaticDiagInfoRec to pack better.  Otherwise,
 // StaticDiagInfoRec would have extra padding on 64-bit platforms.
 const uint32_t StaticDiagInfoDescriptionOffsets[] = {
 #define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             REASON)                                      \
   offsetof(StaticDiagInfoDescriptionStringTable, ENUM##_desc),
 // clang-format off
 #include "clang/Basic/DiagnosticCommonKinds.inc"
 #include "clang/Basic/DiagnosticDriverKinds.inc"
 #include "clang/Basic/DiagnosticFrontendKinds.inc"
 #include "clang/Basic/DiagnosticSerializationKinds.inc"
 #include "clang/Basic/DiagnosticLexKinds.inc"
 #include "clang/Basic/DiagnosticParseKinds.inc"
 #include "clang/Basic/DiagnosticASTKinds.inc"
 #include "clang/Basic/DiagnosticCommentKinds.inc"
 #include "clang/Basic/DiagnosticCrossTUKinds.inc"
 #include "clang/Basic/DiagnosticSemaKinds.inc"
 #include "clang/Basic/DiagnosticAnalysisKinds.inc"
 #include "clang/Basic/DiagnosticRefactoringKinds.inc"
-  // clang-format on
 #undef DIAG
 };
 
+// Reason.Legacy
+struct StaticDiagInfoReasonStringTable {
+#define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             REASON)                                      \
+  char ENUM##_reason[sizeof(REASON)];
+  // clang-format off
+#include "clang/Basic/DiagnosticCommonKinds.inc"
+#include "clang/Basic/DiagnosticDriverKinds.inc"
+#include "clang/Basic/DiagnosticFrontendKinds.inc"
+#include "clang/Basic/DiagnosticSerializationKinds.inc"
+#include "clang/Basic/DiagnosticLexKinds.inc"
+#include "clang/Basic/DiagnosticParseKinds.inc"
+#include "clang/Basic/DiagnosticASTKinds.inc"
+#include "clang/Basic/DiagnosticCommentKinds.inc"
+#include "clang/Basic/DiagnosticCrossTUKinds.inc"
+#include "clang/Basic/DiagnosticSemaKinds.inc"
+#include "clang/Basic/DiagnosticAnalysisKinds.inc"
+#include "clang/Basic/DiagnosticRefactoringKinds.inc"
+  // clang-format on
+#undef DIAG
+};
+
+const StaticDiagInfoReasonStringTable
+    StaticDiagInfoReasons = {
+#define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             REASON)                                      \
+  REASON,
+// clang-format off
+#include "clang/Basic/DiagnosticCommonKinds.inc"
+#include "clang/Basic/DiagnosticDriverKinds.inc"
+#include "clang/Basic/DiagnosticFrontendKinds.inc"
+#include "clang/Basic/DiagnosticSerializationKinds.inc"
+#include "clang/Basic/DiagnosticLexKinds.inc"
+#include "clang/Basic/DiagnosticParseKinds.inc"
+#include "clang/Basic/DiagnosticASTKinds.inc"
+#include "clang/Basic/DiagnosticCommentKinds.inc"
+#include "clang/Basic/DiagnosticCrossTUKinds.inc"
+#include "clang/Basic/DiagnosticSemaKinds.inc"
+#include "clang/Basic/DiagnosticAnalysisKinds.inc"
+#include "clang/Basic/DiagnosticRefactoringKinds.inc"
+// clang-format on
+#undef DIAG
+};
+
+// Stored separately from StaticDiagInfoRec to pack better.  Otherwise,
+// StaticDiagInfoRec would have extra padding on 64-bit platforms.
+const uint32_t StaticDiagInfoReasonOffsets[] = {
+#define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY,            \
+             REASON)                                      \
+  offsetof(StaticDiagInfoReasonStringTable, ENUM##_reason),
+// clang-format off
+#include "clang/Basic/DiagnosticCommonKinds.inc"
+#include "clang/Basic/DiagnosticDriverKinds.inc"
+#include "clang/Basic/DiagnosticFrontendKinds.inc"
+#include "clang/Basic/DiagnosticSerializationKinds.inc"
+#include "clang/Basic/DiagnosticLexKinds.inc"
+#include "clang/Basic/DiagnosticParseKinds.inc"
+#include "clang/Basic/DiagnosticASTKinds.inc"
+#include "clang/Basic/DiagnosticCommentKinds.inc"
+#include "clang/Basic/DiagnosticCrossTUKinds.inc"
+#include "clang/Basic/DiagnosticSemaKinds.inc"
+#include "clang/Basic/DiagnosticAnalysisKinds.inc"
+#include "clang/Basic/DiagnosticRefactoringKinds.inc"
+// clang-format on
+#undef DIAG
+};
+
 // Diagnostic classes.
 enum {
   CLASS_NOTE       = 0x01,
   CLASS_REMARK     = 0x02,
   CLASS_WARNING    = 0x03,
   CLASS_EXTENSION  = 0x04,
   CLASS_ERROR      = 0x05
 };
 
 struct StaticDiagInfoRec {
   uint16_t DiagID;
   uint8_t DefaultSeverity : 3;
   uint8_t Class : 3;
   uint8_t SFINAE : 2;
   uint8_t Category : 6;
   uint8_t WarnNoWerror : 1;
   uint8_t WarnShowInSystemHeader : 1;
   uint8_t WarnShowInSystemMacro : 1;
 
   uint16_t OptionGroupIndex : 15;
   uint16_t Deferrable : 1;
 
   uint16_t DescriptionLen;
+  uint16_t ReasonLen;
 
   unsigned getOptionGroupIndex() const {
     return OptionGroupIndex;
   }
 
   StringRef getDescription() const {
     size_t MyIndex = this - &StaticDiagInfo[0];
     uint32_t StringOffset = StaticDiagInfoDescriptionOffsets[MyIndex];
     const char* Table = reinterpret_cast<const char*>(&StaticDiagInfoDescriptions);
     return StringRef(&Table[StringOffset], DescriptionLen);
   }
 
+  StringRef getReason() const {
+    size_t MyIndex = this - &StaticDiagInfo[0];
+    uint32_t StringOffset = StaticDiagInfoReasonOffsets[MyIndex];
+    const char *Table =
+        reinterpret_cast<const char *>(&StaticDiagInfoReasons);
+    return StringRef(&Table[StringOffset], ReasonLen);
+  }
+
   diag::Flavor getFlavor() const {
     return Class == CLASS_REMARK ? diag::Flavor::Remark
                                  : diag::Flavor::WarningOrError;
   }
 
   bool operator<(const StaticDiagInfoRec &RHS) const {
     return DiagID < RHS.DiagID;
   }

 VALIDATE_DIAG_SIZE(ANALYSIS)
 VALIDATE_DIAG_SIZE(REFACTORING)
 #undef VALIDATE_DIAG_SIZE
 #undef STRINGIFY_NAME
 
 const StaticDiagInfoRec StaticDiagInfo[] = {
 // clang-format off
 #define DIAG(ENUM, CLASS, DEFAULT_SEVERITY, DESC, GROUP, SFINAE, NOWERROR,     \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY)            \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFERRABLE, CATEGORY, REASON)    \
   {                                                                            \
       diag::ENUM,                                                              \
       DEFAULT_SEVERITY,                                                        \
       CLASS,                                                                   \
       DiagnosticIDs::SFINAE,                                                   \
       CATEGORY,                                                                \
       NOWERROR,                                                                \
       SHOWINSYSHEADER,                                                         \
       SHOWINSYSMACRO,                                                          \
       GROUP,                                                                   \
       DEFERRABLE,                                                              \
-      STR_SIZE(DESC, uint16_t)},
+      STR_SIZE(DESC, uint16_t), \
+      STR_SIZE(REASON, uint16_t)},
 #include "clang/Basic/DiagnosticCommonKinds.inc"
 #include "clang/Basic/DiagnosticDriverKinds.inc"
 #include "clang/Basic/DiagnosticFrontendKinds.inc"
 #include "clang/Basic/DiagnosticSerializationKinds.inc"
 #include "clang/Basic/DiagnosticLexKinds.inc"
 #include "clang/Basic/DiagnosticParseKinds.inc"
 #include "clang/Basic/DiagnosticASTKinds.inc"
 #include "clang/Basic/DiagnosticCommentKinds.inc"
static const StaticDiagInfoRec *GetDiagInfo(unsigned DiagID) {
   //    diagnostic and of the category the diagnostic is in. This gives us
   //    the offset of the category in the table.
   // 2. Subtract the number of IDs in each category from our ID. This gives us
   //    the offset of the diagnostic in the category.
   // This is cheaper than a binary search on the table as it doesn't touch
   // memory at all.
   unsigned Offset = 0;
   unsigned ID = DiagID - DIAG_START_COMMON - 1;
-#define CATEGORY(NAME, PREV) \
-  if (DiagID > DIAG_START_##NAME) { \
-    Offset += NUM_BUILTIN_##PREV##_DIAGNOSTICS - DIAG_START_##PREV - 1; \
-    ID -= DIAG_START_##NAME - DIAG_START_##PREV; \
+#define CATEGORY(NAME, PREV)                                                   \
+  if (DiagID > DIAG_START_##NAME) {                                            \
+    Offset += NUM_BUILTIN_##PREV##_DIAGNOSTICS - DIAG_START_##PREV - 1;        \
+    ID -= DIAG_START_##NAME - DIAG_START_##PREV;                               \
   }
   CATEGORY(DRIVER, COMMON)
   CATEGORY(FRONTEND, DRIVER)
   CATEGORY(SERIALIZATION, FRONTEND)
   CATEGORY(LEX, SERIALIZATION)
   CATEGORY(PARSE, LEX)
   CATEGORY(AST, PARSE)
   CATEGORY(COMMENT, AST)
   CATEGORY(CROSSTU, COMMENT)
   CATEGORY(SEMA, CROSSTU)
   CATEGORY(ANALYSIS, SEMA)
   CATEGORY(REFACTORING, ANALYSIS)
 #undef CATEGORY
 
   // Avoid out of bounds reads.
   if (ID + Offset >= StaticDiagInfoSize)
     return nullptr;
 
   assert(ID < StaticDiagInfoSize && Offset < StaticDiagInfoSize);
 

 /// DiagID belongs to, or 0 if no category.
 unsigned DiagnosticIDs::getCategoryNumberForDiag(unsigned DiagID) {
   if (const StaticDiagInfoRec *Info = GetDiagInfo(DiagID))
     return Info->Category;
   return 0;
 }
 
 namespace {
-  // The diagnostic category names.
-  struct StaticDiagCategoryRec {
-    const char *NameStr;
-    uint8_t NameLen;
 
-    StringRef getName() const {
-      return StringRef(NameStr, NameLen);
-    }
-  };
 }
 
 // Unfortunately, the split between DiagnosticIDs and Diagnostic is not
 // particularly clean, but for now we just implement this method here so we can
 // access GetDefaultDiagMapping.
 DiagnosticMapping &
 DiagnosticsEngine::DiagState::getOrAddMapping(diag::kind Diag) {
   std::pair<iterator, bool> Result =
unsigned DiagnosticIDs::getNumberOfCategories() {
   return std::size(CategoryNameTable) - 1;
 }
 
 /// getCategoryNameFromID - Given a category ID, return the name of the
 /// category, an empty string if CategoryID is zero, or null if CategoryID is
 /// invalid.
 StringRef DiagnosticIDs::getCategoryNameFromID(unsigned CategoryID) {
   if (CategoryID >= getNumberOfCategories())
     return StringRef();
   return CategoryNameTable[CategoryID].getName();
 }
 
 
 
 DiagnosticIDs::SFINAEResponse
 DiagnosticIDs::getDiagnosticSFINAEResponse(unsigned DiagID) {
   if (const StaticDiagInfoRec *Info = GetDiagInfo(DiagID))

 
 //===----------------------------------------------------------------------===//
 // Custom Diagnostic information
 //===----------------------------------------------------------------------===//
 
 namespace clang {
   namespace diag {
     class CustomDiagInfo {
-      typedef std::pair<DiagnosticIDs::Level, std::string> DiagDesc;
+      struct DiagDesc {
+        DiagnosticIDs::Level Level;
+        std::string Message;
+        DiagnosticReason Reason;
+
+        // FIXME(spaceship): default when C++20 becomes the default
+        bool operator==(const DiagDesc &Other) const {
+          return std::tie(Level, Message, Reason) ==
+                 std::tie(Other.Level, Other.Message, Other.Reason);
+        }
+
+        bool operator!=(const DiagDesc &Other) const { return !(*this == Other); }
+
+        bool operator<(const DiagDesc &Other) const {
+          return std::tie(Level, Message, Reason) <
+                 std::tie(Other.Level, Other.Message, Other.Reason);
+        }
+
+        bool operator>(const DiagDesc &Other) const { return Other < *this; }
+
+        bool operator<=(const DiagDesc &Other) const { return !(Other < *this); }
+
+        bool operator>=(const DiagDesc &Other) const { return !(*this < Other); }
+      };
       std::vector<DiagDesc> DiagInfo;
       std::map<DiagDesc, unsigned> DiagIDs;
-    public:
 
+      bool IsValidDiagnosticID(unsigned DiagID) const {
+        return DiagID - DIAG_UPPER_LIMIT < DiagInfo.size();
+      }
+
+    public:
       /// getDescription - Return the description of the specified custom
       /// diagnostic.
       StringRef getDescription(unsigned DiagID) const {
-        assert(DiagID - DIAG_UPPER_LIMIT < DiagInfo.size() &&
-               "Invalid diagnostic ID");
-        return DiagInfo[DiagID-DIAG_UPPER_LIMIT].second;
+        assert(IsValidDiagnosticID(DiagID) && "Invalid diagnostic ID");
+        return DiagInfo[DiagID - DIAG_UPPER_LIMIT].Message;
+      }
+
+      StringRef getReason(unsigned DiagID) const {
+        assert(IsValidDiagnosticID(DiagID) && "Invalid diagnostic ID");
+        return DiagInfo[DiagID - DIAG_UPPER_LIMIT].Reason.Value;
       }
 
       /// getLevel - Return the level of the specified custom diagnostic.
       DiagnosticIDs::Level getLevel(unsigned DiagID) const {
-        assert(DiagID - DIAG_UPPER_LIMIT < DiagInfo.size() &&
-               "Invalid diagnostic ID");
-        return DiagInfo[DiagID-DIAG_UPPER_LIMIT].first;
+        assert(IsValidDiagnosticID(DiagID) && "Invalid diagnostic ID");
+        return DiagInfo[DiagID - DIAG_UPPER_LIMIT].Level;
       }
 
       unsigned getOrCreateDiagID(DiagnosticIDs::Level L, StringRef Message,
+                                 const DiagnosticReason &Reason,
                                  DiagnosticIDs &Diags) {
-        DiagDesc D(L, std::string(Message));
+        DiagDesc D{L, std::string(Message), Reason};
         // Check to see if it already exists.
         std::map<DiagDesc, unsigned>::iterator I = DiagIDs.lower_bound(D);
         if (I != DiagIDs.end() && I->first == D)
           return I->second;
 
         // If not, assign a new ID.
         unsigned ID = DiagInfo.size()+DIAG_UPPER_LIMIT;
         DiagIDs.insert(std::make_pair(D, ID));

 DiagnosticIDs::~DiagnosticIDs() {}
 
 /// getCustomDiagID - Return an ID for a diagnostic with the specified message
 /// and level.  If this is the first request for this diagnostic, it is
 /// registered and created, otherwise the existing ID is returned.
 ///
 /// \param FormatString A fixed diagnostic format string that will be hashed and
 /// mapped to a unique DiagID.
-unsigned DiagnosticIDs::getCustomDiagID(Level L, StringRef FormatString) {
+unsigned DiagnosticIDs::getCustomDiagID(Level L, StringRef FormatString,
+                                        const DiagnosticReason &Reason) {
   if (!CustomDiagInfo)
     CustomDiagInfo.reset(new diag::CustomDiagInfo());
-  return CustomDiagInfo->getOrCreateDiagID(L, FormatString, *this);
+  return CustomDiagInfo->getOrCreateDiagID(L, FormatString, Reason, *this);
 }
 
 
 /// isBuiltinWarningOrExtension - Return true if the unmapped diagnostic
 /// level of the specified diagnostic ID is a Warning or Extension.
 /// This only works on builtin diagnostics, not custom ones, and is not legal to
 /// call on NOTEs.
 bool DiagnosticIDs::isBuiltinWarningOrExtension(unsigned DiagID) {
   return DiagID < diag::DIAG_UPPER_LIMIT &&
          getBuiltinDiagClass(DiagID) != CLASS_ERROR;
 }
 
 /// Determine whether the given built-in diagnostic ID is a
 /// Note.
 bool DiagnosticIDs::isBuiltinNote(unsigned DiagID) {
   return DiagID < diag::DIAG_UPPER_LIMIT &&
          getBuiltinDiagClass(DiagID) == CLASS_NOTE;
 }
 
 /// isBuiltinExtensionDiag - Determine whether the given built-in diagnostic
 /// ID is for an extension of some sort.  This also returns EnabledByDefault,
 /// which is set to indicate whether the diagnostic is ignored by default (in
 /// which case -pedantic enables it) or treated as a warning/error by default.
 ///
 bool DiagnosticIDs::isBuiltinExtensionDiag(unsigned DiagID,
                                            bool &EnabledByDefault) {
   if (DiagID >= diag::DIAG_UPPER_LIMIT ||
       getBuiltinDiagClass(DiagID) != CLASS_EXTENSION)
     return false;
 
   EnabledByDefault =
       GetDefaultDiagMapping(DiagID).getSeverity() != diag::Severity::Ignored;
   return true;
 }

 /// issue.
 StringRef DiagnosticIDs::getDescription(unsigned DiagID) const {
   if (const StaticDiagInfoRec *Info = GetDiagInfo(DiagID))
     return Info->getDescription();
   assert(CustomDiagInfo && "Invalid CustomDiagInfo");
   return CustomDiagInfo->getDescription(DiagID);
 }
 
+StringRef DiagnosticIDs::getReason(unsigned DiagID) const {
+  if (const StaticDiagInfoRec *Info = GetDiagInfo(DiagID))
+    return Info->getReason();
+  assert(CustomDiagInfo && "Invalid CustomDiagInfo");
+  return CustomDiagInfo->getReason(DiagID);
+}
+
 static DiagnosticIDs::Level toLevel(diag::Severity SV) {
   switch (SV) {
   case diag::Severity::Ignored:
     return DiagnosticIDs::Ignored;
   case diag::Severity::Remark:
     return DiagnosticIDs::Remark;
   case diag::Severity::Warning:
     return DiagnosticIDs::Warning;
DiagnosticIDs::getDiagnosticSeverity(unsigned DiagID, SourceLocation Loc,
   return Result;
 }
 
 #define GET_DIAG_ARRAYS
 #include "clang/Basic/DiagnosticGroups.inc"
 #undef GET_DIAG_ARRAYS
 
 namespace {
-  struct WarningOption {
-    uint16_t NameOffset;
-    uint16_t Members;
-    uint16_t SubGroups;
-    StringRef Documentation;
 
-    // String is stored with a pascal-style length byte.
-    StringRef getName() const {
-      return StringRef(DiagGroupNames + NameOffset + 1,
-                       DiagGroupNames[NameOffset]);
-    }
-  };
 }
 
 // Second the table of options, sorted by name for fast binary lookup.
 static const WarningOption OptionTable[] = {
 #define DIAG_ENTRY(GroupName, FlagNameOffset, Members, SubGroups, Docs)        \
   {FlagNameOffset, Members, SubGroups, Docs},
 #include "clang/Basic/DiagnosticGroups.inc"
 #undef DIAG_ENTRY
for (; *SubGroups != (int16_t)-1; ++SubGroups)
     NotFound &= getDiagnosticsInGroup(Flavor, &OptionTable[(short)*SubGroups],
                                       Diags);
 
   return NotFound;
 }
 
 bool
 DiagnosticIDs::getDiagnosticsInGroup(diag::Flavor Flavor, StringRef Group,
-                                     SmallVectorImpl<diag::kind> &Diags) const {
   if (llvm::Optional<diag::Group> G = getGroupForWarningOption(Group))
     return ::getDiagnosticsInGroup(
         Flavor, &OptionTable[static_cast<unsigned>(*G)], Diags);
   return true;
 }
 
 void DiagnosticIDs::getAllDiagnostics(diag::Flavor Flavor,
                                       std::vector<diag::kind> &Diags) {

clang/lib/Frontend/ASTUnit.cpp

for (const auto &FixIt : SD.FixIts) {
       FixIts.push_back(FixItHint());
       FixItHint &FH = FixIts.back();
       FH.CodeToInsert = FixIt.CodeToInsert;
       SourceLocation BL = FileLoc.getLocWithOffset(FixIt.RemoveRange.first);
       SourceLocation EL = FileLoc.getLocWithOffset(FixIt.RemoveRange.second);
       FH.RemoveRange = CharSourceRange::getCharRange(BL, EL);
     }
 
-    Result.push_back(StoredDiagnostic(SD.Level, SD.ID,
-                                      SD.Message, Loc, Ranges, FixIts));
+    Result.push_back(StoredDiagnostic(SD.Level, SD.ID, SD.Message, SD.Reason,
+                                      Loc, Ranges, FixIts));
   }
   Result.swap(Out);
 }
 
 void ASTUnit::addFileLevelDecl(Decl *D) {
   assert(D);
 
   // We only care about local declarations.

clang/test/TableGen/DiagnosticBase.inc

class DiagGroup<string Name, list<DiagGroup> subgroups = []> {
   string GroupName = Name;
   list<DiagGroup> SubGroups = subgroups;
   string CategoryName = "";
   code Documentation = [{}];
 }
 class InGroup<DiagGroup G> { DiagGroup Group = G; }
 //class IsGroup<string Name> { DiagGroup Group = DiagGroup<Name>; }
 
+// Structured diagnostics enable us to have diagnostics that contain a headline
+// description and a detailed description. DiagReason represents the latter,
+// although some subengines might combine the two into a single message.
+class DiagReason<string value> {
+  string Value = value;
+}
+def NO_REASON_YET : DiagReason<"">;
 include "DiagnosticDocs.inc"
 
 // All diagnostics emitted by the compiler are an indirect subclass of this.
-class Diagnostic<string summary, DiagClass DC, Severity defaultmapping> {
+class Diagnostic<string summary, DiagClass DC, Severity defaultmapping, DiagReason reason> {
   /// Component is specified by the file with a big let directive.
   string         Component = ?;
   string         Summary = summary;
   DiagClass      Class = DC;
   SFINAEResponse SFINAE = SFINAE_Suppress;
   bit            AccessControl = 0;
   bit            WarningNoWerror = 0;
   bit            ShowInSystemHeader = 0;
   bit            ShowInSystemMacro = 1;
   bit            Deferrable = 0;
   Severity       DefaultSeverity = defaultmapping;
   DiagGroup      Group;
   string         CategoryName = "";
+  DiagReason     Reason = reason;
 }
 
 class SFINAEFailure {
   SFINAEResponse SFINAE = SFINAE_SubstitutionFailure;
 }
 class NoSFINAE {
   SFINAEResponse SFINAE = SFINAE_Report;
 }
class Deferrable {
   bit Deferrable = 1;
 }
 
 class NonDeferrable {
   bit Deferrable = 0;
 }
 
 // FIXME: ExtWarn and Extension should also be SFINAEFailure by default.
-class Error<string str>     : Diagnostic<str, CLASS_ERROR, SEV_Error>, SFINAEFailure {
+class Error<string str, DiagReason reason = NO_REASON_YET>     : Diagnostic<str, CLASS_ERROR, SEV_Error, reason>, SFINAEFailure {
   bit ShowInSystemHeader = 1;
 }
 // Warnings default to on (but can be default-off'd with DefaultIgnore).
 // This is used for warnings about questionable code; warnings about
 // accepted language extensions should use Extension or ExtWarn below instead.
-class Warning<string str>   : Diagnostic<str, CLASS_WARNING, SEV_Warning>;
+class Warning<string str, DiagReason reason = NO_REASON_YET>   : Diagnostic<str, CLASS_WARNING, SEV_Warning, reason>;
 // Remarks can be turned on with -R flags and provide commentary, e.g. on
 // optimizer decisions.
-class Remark<string str>    : Diagnostic<str, CLASS_REMARK, SEV_Ignored>;
+class Remark<string str, DiagReason reason = NO_REASON_YET>    : Diagnostic<str, CLASS_REMARK, SEV_Ignored, reason>;
 // Extensions are warnings about accepted language extensions.
 // Extension warnings are default-off but enabled by -pedantic.
-class Extension<string str> : Diagnostic<str, CLASS_EXTENSION, SEV_Ignored>;
+class Extension<string str, DiagReason reason = NO_REASON_YET> : Diagnostic<str, CLASS_EXTENSION, SEV_Ignored, reason>;
 // ExtWarns are warnings about accepted language extensions.
 // ExtWarn warnings are default-on.
-class ExtWarn<string str>   : Diagnostic<str, CLASS_EXTENSION, SEV_Warning>;
+class ExtWarn<string str, DiagReason reason = NO_REASON_YET>   : Diagnostic<str, CLASS_EXTENSION, SEV_Warning, reason>;
 // Notes can provide supplementary information on errors, warnings, and remarks.
-class Note<string str>      : Diagnostic<str, CLASS_NOTE, SEV_Fatal/*ignored*/>;
+class Note<string str, DiagReason reason = NO_REASON_YET>      : Diagnostic<str, CLASS_NOTE, SEV_Fatal/*ignored*/, reason>;
 
 
 class DefaultIgnore { Severity DefaultSeverity = SEV_Ignored; }
 class DefaultWarn   { Severity DefaultSeverity = SEV_Warning; }
 class DefaultError  { Severity DefaultSeverity = SEV_Error; }
 class DefaultFatal  { Severity DefaultSeverity = SEV_Fatal; }
 class DefaultWarnNoWerror {
   bit WarningNoWerror = 1;
 }
 class DefaultRemark { Severity DefaultSeverity = SEV_Remark; }

clang/test/TableGen/deferred-diag.td

 // RUN: clang-tblgen -gen-clang-diags-defs -I%S %s -o - 2>&1 | \
 // RUN:    FileCheck --strict-whitespace %s
 include "DiagnosticBase.inc"
 
 // Test usage of Deferrable and NonDeferrable in diagnostics.
 
 def test_default : Error<"This error is non-deferrable by default">;
-// CHECK-DAG: DIAG(test_default, {{.*}}SFINAE_SubstitutionFailure, false, true, true, false, 0)
+// CHECK-DAG: DIAG(test_default, {{.*}}SFINAE_SubstitutionFailure, false, true, true, false, 0, /*Reason=*/"")
 
 def test_deferrable : Error<"This error is deferrable">, Deferrable;
-// CHECK-DAG: DIAG(test_deferrable, {{.*}} SFINAE_SubstitutionFailure, false, true, true, true, 0)
+// CHECK-DAG: DIAG(test_deferrable, {{.*}} SFINAE_SubstitutionFailure, false, true, true, true, 0, /*Reason=*/"")
 
 def test_non_deferrable : Error<"This error is non-deferrable">, NonDeferrable;
-// CHECK-DAG: DIAG(test_non_deferrable, {{.*}} SFINAE_SubstitutionFailure, false, true, true, false, 0)
+// CHECK-DAG: DIAG(test_non_deferrable, {{.*}} SFINAE_SubstitutionFailure, false, true, true, false, 0, /*Reason=*/"")
 
 let Deferrable = 1 in {
 
 def test_let : Error<"This error is deferrable by let">;
-// CHECK-DAG: DIAG(test_let, {{.*}} SFINAE_SubstitutionFailure, false, true, true, true, 0)
+// CHECK-DAG: DIAG(test_let, {{.*}} SFINAE_SubstitutionFailure, false, true, true, true, 0, /*Reason=*/"")
 
 // Make sure TextSubstitution is allowed in the let Deferrable block.
 def textsub : TextSubstitution<"%select{text1|text2}0">;
 
 def test_let2 : Error<"This error is deferrable by let %sub{textsub}0">;
-// CHECK-DAG: DIAG(test_let2, {{.*}} SFINAE_SubstitutionFailure, false, true, true, true, 0)
+// CHECK-DAG: DIAG(test_let2, {{.*}} SFINAE_SubstitutionFailure, false, true, true, true, 0, /*Reason=*/"")
 
 }

clang/tools/diagtool/DiagnosticNames.cpp

llvm::ArrayRef<DiagnosticRecord> diagtool::getBuiltinDiagnosticsByName() {
   return llvm::makeArrayRef(BuiltinDiagnosticsByName);
 }
 
 
 // FIXME: Is it worth having two tables, especially when this one can get
 // out of sync easily?
 static const DiagnosticRecord BuiltinDiagnosticsByID[] = {
 #define DIAG(ENUM, CLASS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, NOWERROR,      \
-             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFER, CATEGORY)                 \
+             SHOWINSYSHEADER, SHOWINSYSMACRO, DEFER, CATEGORY, REASON)         \
   {#ENUM, diag::ENUM, STR_SIZE(#ENUM, uint8_t)},
 #include "clang/Basic/DiagnosticCommonKinds.inc"
 #include "clang/Basic/DiagnosticCrossTUKinds.inc"
 #include "clang/Basic/DiagnosticDriverKinds.inc"
 #include "clang/Basic/DiagnosticFrontendKinds.inc"
 #include "clang/Basic/DiagnosticSerializationKinds.inc"
 #include "clang/Basic/DiagnosticLexKinds.inc"
 #include "clang/Basic/DiagnosticParseKinds.inc"

clang/utils/TableGen/ClangDiagnosticsEmitter.cpp

for (Record *Diag : Records.getAllDerivedDefinitions("Diagnostic")) {
             Diag->getLoc(),
             "Diagnostic '" + Name +
                 "' has same name as TextSubstitution definition");
     }
   }
 
   std::vector<std::string> buildForDocumentation(StringRef Role,
                                                  const Record *R);
-  std::string buildForDefinition(const Record *R);
+  std::string buildForDefinition(const Record *R, StringRef Field);
 
   Piece *getSubstitution(SubstitutionPiece *S) const {
     auto It = Substitutions.find(S->Name);
     if (It == Substitutions.end())
       PrintFatalError("Failed to find substitution with name: " + S->Name);
     return It->second.Root;
   }
 
if (!MP) {
     D.Root = MP;
   }
   MP->Pieces.insert(MP->Pieces.begin(), Prefix);
   std::vector<std::string> Result;
   DiagTextDocPrinter{*this, Result}.Visit(D.Root);
   return Result;
 }
 
-std::string DiagnosticTextBuilder::buildForDefinition(const Record *R) {
+std::string DiagnosticTextBuilder::buildForDefinition(const Record *R,
+                                                      StringRef Field) {
   EvaluatingRecordGuard Guard(&EvaluatingRecord, R);
-  StringRef Text = R->getValueAsString("Summary");
+  StringRef Text = R->getValueAsString(Field);
   DiagText D(*this, Text);
   std::string Result;
   DiagTextPrinter{*this, Result}.Visit(D.Root);
   return Result;
 }
 
 } // namespace
 
for (unsigned i = 0, e = Diags.size(); i != e; ++i) {
 
     OS << "DIAG(" << R.getName() << ", ";
     OS << R.getValueAsDef("Class")->getName();
     OS << ", (unsigned)diag::Severity::"
        << R.getValueAsDef("DefaultSeverity")->getValueAsString("Name");
 
     // Description string.
     OS << ", \"";
-    OS.write_escaped(DiagTextBuilder.buildForDefinition(&R)) << '"';
+    OS.write_escaped(DiagTextBuilder.buildForDefinition(&R, "Summary")) << '"';
 
     // Warning group associated with the diagnostic. This is stored as an index
     // into the alphabetically sorted warning group table.
     if (DefInit *DI = dyn_cast<DefInit>(R.getValueInit("Group"))) {
       std::map<std::string, GroupInfo>::iterator I = DiagsInGroup.find(
           std::string(DI->getDef()->getValueAsString("GroupName")));
       assert(I != DiagsInGroup.end());
       OS << ", " << I->second.IDNo;
for (unsigned i = 0, e = Diags.size(); i != e; ++i) {
 
     if (R.getValueAsBit("Deferrable"))
       OS << ", true";
     else
       OS << ", false";
 
     // Category number.
     OS << ", " << CategoryIDs.getID(getDiagnosticCategory(&R, DGParentMap));
+
+    // Reasons
+    OS << ", /*Reason=*/\"";
+    OS.write_escaped(DiagTextBuilder.buildForDefinition(
+        R.getValueAsDef("Reason"), "Value"))
+        << '"';
     OS << ")\n";
   }
 }
 
 //===----------------------------------------------------------------------===//
 // Warning Group Tables generation
 //===----------------------------------------------------------------------===//