[Clang Tablegen][RFC] Allow Early Textual Substitutions in `Diagnostic` messages.

[EricWF]

Summary

There are cases where the same string or select is repeated verbatim in a lot of diagnostics. This can be a pain to maintain and update. Tablegen provides no way stash the common text somewhere and reuse it in the diagnostics, until now!

This patch allows diagnostic texts to contain %sub{<definition-name>}, where <definition-name> names a Tablegen record of type TextSubstitution. These substitutions are done early, before the diagnostic string is otherwise processed. All %sub modifiers will be replaced before the diagnostic definitions are emitted.

The substitution must specify all arguments used by the substitution, and modifier indexes in the substitution are re-numbered accordingly. For example:

def select_ovl_candidate : TextSubstitution<"%select{function|constructor}0%select{| template| %2}1">;

when used as

"candidate `%sub{select_ovl_candidate}3,2,1 not viable"

will act as if we wrote:

"candidate %select{function|constructor}3%select{| template| %1}2 not viable"

[EricWF]

Fix copy paste error.

[rjmccall]

This seems like a good idea to me. I wonder if it would be better to take advantage of this to shrink the string tables by preserving the substitution structure until runtime, but that really doesn't need to be part of this first try.

utils/TableGen/ClangDiagnosticsEmitter.cpp

1131

I see why this has to be done separately, I think, but it should at least go in a helper function.

Also, please check for substitution-name conflicts.

[rsmith]

Thank you, I've been wanting this for ages but never got around to it :)

(I'd been thinking about doing this by adding custom enum -> text mappings, but I think your approach is at least somewhat more general.)

include/clang/Basic/DiagnosticSemaKinds.td

3626–3634

Why do some of these have trailing spaces and others not? That looks wrong to me.

3648

... and this is the reason. %1 is sometimes empty and sometimes non-empty, and we're "cunningly" passing that information through %0. Yuck.

It looks like this particular diagnostic refactoring can't work quite like this if we want it to be whitespace-correct (which I think we do), because some uses of your factored-out text also include a name and others don't. Perhaps adding another select on %0 that either adds a space or not would work, or two separate substitutions for the "include name" and "don't include name" cases?

More generally I wonder if we actually want to renumber %i's through a %sub, so that we could define the substitution as

TextSubstitution<
   "%select{function|function|constructor|function %1|function %1|constructor %1|...}0">

and then use it as, eg

"candidate %sub{select_ovl_candidate_kind_with_name}5,6 not viable"

and have it act as if we wrote

"candidate %select{function|function|constructor|function %6|function %6|constructor %6|...}5 not viable">

I expect we'll need that pretty much as soon as we have a substitution that takes more than one parameter, and I think we want a multi-parameter substitution for this refactoring :)

[EricWF]

@rsmith How does this look?

Turns out we have to fully parse the diagnostic text in order to substitute modifier indexes, which is a bit of a complication. This patch does exactly that.

There is still some work done to produce useful error messages when the substitution is ill-formed, but hopefully the design of this patch is, in general, OK>

[EricWF]

test/TableGen/text-substitution.td

9

This test TBD. The emit-diag-docs.td test should hit all the major cases.

[EricWF]

• Update tests.

The last thing I want to tackle is improving parsing errors to at least name the diagnostic being parsed. Naming *why* it's invalid if we don't provide its name.

[EricWF]

@rsmith Can select indexes be negative? What's the correct type to represent them? Existing code seems to use int, but the LLVM style seems to suggest unsigned is more appropriate.

utils/TableGen/ClangDiagnosticsEmitter.cpp

591

This is unused. Removing.

[EricWF]

• Get argument renumbering work as @rsmith requested.
• Make the changes to existing diagnostics whitespace correct.
• Cleanup DiagnosticSemaKinds.td and SemaOverload.cpp to take advantage of this change.

@rsmith, @rjmccall: This change set is a lot larger now. Is it appropriate to commit the Sema cleanup with this patch?

[EricWF]

Document %sub in InternalsManual.rst

[rsmith]

Thanks, this is great.

In D46740#1096859, @EricWF wrote:

Turns out we have to fully parse the diagnostic text in order to substitute modifier indexes, which is a bit of a complication. This patch does exactly that.

I like that you were able to reuse the existing parsing code for documentation generation here.

In D46740#1096868, @EricWF wrote:

@rsmith Can select indexes be negative? What's the correct type to represent them? Existing code seems to use int, but the LLVM style seems to suggest unsigned is more appropriate.

No, select indexes must be in the range 0..<number of options-1>. I don't think we actually have a convention of using unsigned for integers that can't be negative, and I suspect that if we thought about a policy we'd pick the opposite one :)

In D46740#1096972, @EricWF wrote:

@rsmith, @rjmccall: This change set is a lot larger now. Is it appropriate to commit the Sema cleanup with this patch?

I would ideally like to see one substitution added, and one set of diagnostics converted, as part of this patch, and for other diagnostics to be converted in separate changes after that.

docs/InternalsManual.rst

337 ↗

(On Diff #146495)

Missing the sub specifier here?

341–342 ↗

(On Diff #146495)

I don't think "Class:" makes sense here, since what this specifier consumes depends on its replacement string. "Class: varies" or similar might work, but maybe just drop it?

include/clang/Basic/DiagnosticSemaKinds.td

3526–3544

Is there a reason this one wasn't changed to use %sub?

test/TableGen/DiagnosticBase.inc

1–25

This is the wrong filename.

[EricWF]

In D46740#1097014, @rsmith wrote:

Thanks, this is great.

In D46740#1096859, @EricWF wrote:

Turns out we have to fully parse the diagnostic text in order to substitute modifier indexes, which is a bit of a complication. This patch does exactly that.

I like that you were able to reuse the existing parsing code for documentation generation here.

With heavy modifications :-)

But now that we have a full AST representation of diagnostics text, imagine what we can do next!

docs/InternalsManual.rst

341–342 ↗

(On Diff #146495)

Dropping it seems clearer.

include/clang/Basic/DiagnosticSemaKinds.td

3526–3544

It refers to implicit special members differently ("is the implicit default constructor" -> "constructor (the implicit default constructor"). I think I mistakenly thought transforming it would be grammatically incorrect. But looking further it seems fine.

[EricWF]

Address @rsmiths comments.

• Prefer int to unsigned.
• Substitute note_ovl_candidate.
• Fix issues in docs.

[EricWF]

In D46740#1097014, @rsmith wrote:

Thanks, this is great.

In D46740#1096859, @EricWF wrote:

Turns out we have to fully parse the diagnostic text in order to substitute modifier indexes, which is a bit of a complication. This patch does exactly that.

I like that you were able to reuse the existing parsing code for documentation generation here.

With heavy modifications :-)

[EricWF]

Misc cleanups.

• proof read and correct documentation.

[EricWF]

utils/TableGen/ClangDiagnosticsEmitter.cpp

1131

@rjmccall By substitution name conflicts do you mean substitution names which conflict with diagnostic names?

[EricWF]

• Add error if a substitution and a diagnostic share the same name.

Any final comments on this?

[rjmccall]

utils/TableGen/ClangDiagnosticsEmitter.cpp

1131

I meant between substitutions, but I guess that's probably handled automatically by the base TableGen parser, sorry.

[rsmith]

In D46740#1105063, @EricWF wrote:

Any final comments on this?

I would ideally like to see one substitution added, and one set of diagnostics converted, as part of this patch, and for other diagnostics to be converted in separate changes after that. Please pick one that doesn't also require changes to Sema, so this patch is separate from the refactoring of the Sema diagnostic emission.

[EricWF]

• Remove changes to Sema, and overload resolution diagnostics. Only change the special member function diagnostics as an example.

If there are no further comments, I'll commit this once I've run the test suite.

include/clang/Basic/Diagnostic.td

 
 // Responses to a diagnostic in a SFINAE context.
 class SFINAEResponse;
 def SFINAE_SubstitutionFailure : SFINAEResponse;
 def SFINAE_Suppress            : SFINAEResponse;
 def SFINAE_Report              : SFINAEResponse;
 def SFINAE_AccessControl       : SFINAEResponse;
 
+// Textual substitutions which may be performed on the text of diagnostics
+class TextSubstitution<string Text> {
+  string Substitution = Text;
+  // TODO: These are only here to allow substitutions to be declared inline with
+  // diagnostics
+  string Component = "";
+  string CategoryName = "";
+}
+
 // Diagnostic Categories.  These can be applied to groups or individual
 // diagnostics to specify a category.
 class DiagCategory<string Name> {
   string CategoryName = Name;
 }
 
 // Diagnostic Groups.
 class DiagGroup<string Name, list<DiagGroup> subgroups = []> {

include/clang/Basic/DiagnosticSemaKinds.td

   "call to %0 is ambiguous">;
 def err_ovl_deleted_call : Error<
   "call to %select{unavailable|deleted}0 function %1%2">;
 def err_ovl_ambiguous_member_call : Error<
   "call to member function %0 is ambiguous">;
 def err_ovl_deleted_member_call : Error<
   "call to %select{unavailable|deleted}0 member function %1%2">;
 def note_ovl_too_many_candidates : Note<
     "remaining %0 candidate%s0 omitted; "
     "pass -fshow-overloads=all to show them">;
 def note_ovl_candidate : Note<"candidate "
     "%select{function|function|constructor|"
     "function |function |constructor |"
     "is the implicit default constructor|"
     "is the implicit copy constructor|"
     "is the implicit move constructor|"
     "is the implicit copy assignment operator|"
     "is the implicit move assignment operator|"
     "inherited constructor|"
     "inherited constructor }0%2"
     "%select{| has different class%diff{ (expected $ but has $)|}4,5"
     "| has different number of parameters (expected %4 but has %5)"
     "| has type mismatch at %ordinal4 parameter"
     "%diff{ (expected $ but has $)|}5,6"
     "| has different return type%diff{ ($ expected but has $)|}4,5"
     "| has different qualifiers (expected "
     "%select{none|const|restrict|const and restrict|volatile|const and volatile"
     "|volatile and restrict|const, volatile, and restrict}4 but found "
     "%select{none|const|restrict|const and restrict|volatile|const and volatile"
     "|volatile and restrict|const, volatile, and restrict}5)"
     "| has different exception specification}3">;
 
 def note_ovl_candidate_inherited_constructor : Note<
     "constructor from base class %0 inherited here">;
 def note_ovl_candidate_inherited_constructor_slice : Note<

 def note_ovl_candidate_non_deduced_mismatch : Note<
     "candidate template ignored: could not match %diff{$ against $|types}0,1">;
 // This note is needed because the above note would sometimes print two
 // different types with the same name.  Remove this note when the above note
 // can handle that case properly.
 def note_ovl_candidate_non_deduced_mismatch_qualified : Note<
     "candidate template ignored: could not match %q0 against %q1">;
 
-// Note that we don't treat templates differently for this diagnostic.
-def note_ovl_candidate_arity : Note<"candidate "
+def select_ovl_candidate_kind : TextSubstitution<
     "%select{function|function|constructor|function|function|constructor|"
     "constructor (the implicit default constructor)|"
     "constructor (the implicit copy constructor)|"
     "constructor (the implicit move constructor)|"
     "function (the implicit copy assignment operator)|"
     "function (the implicit move assignment operator)|"
     "inherited constructor|"
-    "inherited constructor}0 %select{|template }1"
-    "not viable: requires%select{ at least| at most|}2 %3 argument%s3, but %4 "
-    "%plural{1:was|:were}4 provided">;
-
-def note_ovl_candidate_arity_one : Note<"candidate "
-    "%select{function|function|constructor|function|function|constructor|"
+    "inherited constructor}0">;
+def select_ovl_template_kind : TextSubstitution<
+    "%select{function|function|constructor|"
+    "function |function |constructor |"
     "constructor (the implicit default constructor)|"
     "constructor (the implicit copy constructor)|"
     "constructor (the implicit move constructor)|"
     "function (the implicit copy assignment operator)|"
     "function (the implicit move assignment operator)|"
     "inherited constructor|"
-    "inherited constructor}0 %select{|template }1not viable: "
+    "inherited constructor }0">;
+
+// Note that we don't treat templates differently for this diagnostic.
+def note_ovl_candidate_arity : Note<"candidate "
+    "%sub{select_ovl_candidate_kind}0 %select{|template }1"
+    "not viable: requires%select{ at least| at most|}2 %3 argument%s3, but %4 "
+    "%plural{1:was|:were}4 provided">;
+
+def note_ovl_candidate_arity_one : Note<"candidate "
+    "%sub{select_ovl_candidate_kind}0 %select{|template }1not viable: "
     "%select{requires at least|allows at most single|requires single}2 "
     "argument %3, but %plural{0:no|:%4}4 arguments were provided">;
 
 def note_ovl_candidate_deleted : Note<
-    "candidate %select{function|function|constructor|"
-    "function |function |constructor |"
-    "constructor (the implicit default constructor)|"
-    "constructor (the implicit copy constructor)|"
-    "constructor (the implicit move constructor)|"
-    "function (the implicit copy assignment operator)|"
-    "function (the implicit move assignment operator)|"
-    "inherited constructor|"
-    "inherited constructor }0%1 has been "
+    "candidate %sub{select_ovl_template_kind}0%1 has been "
     "%select{explicitly made unavailable|explicitly deleted|"
     "implicitly deleted}2">;
 
 // Giving the index of the bad argument really clutters this message, and
 // it's relatively unimportant because 1) it's generally obvious which
 // argument(s) are of the given object type and 2) the fix is usually
 // to complete the type, which doesn't involve changes to the call line
 // anyway.  If people complain, we can change it.
 def note_ovl_candidate_bad_conv_incomplete : Note<"candidate "
-    "%select{function|function|constructor|"
-    "function |function |constructor |"
-    "constructor (the implicit default constructor)|"
-    "constructor (the implicit copy constructor)|"
-    "constructor (the implicit move constructor)|"
-    "function (the implicit copy assignment operator)|"
-    "function (the implicit move assignment operator)|"
-    "inherited constructor|"
-    "inherited constructor }0%1 "
+    "%sub{select_ovl_template_kind}0%1 "
     "not viable: cannot convert argument of incomplete type "
     "%diff{$ to $|to parameter type}2,3 for "
     "%select{%ordinal5 argument|object argument}4"
     "%select{|; dereference the argument with *|"
     "; take the address of the argument with &|"
     "; remove *|"
     "; remove &}6">;
 def note_ovl_candidate_bad_list_argument : Note<"candidate "
-    "%select{function|function|constructor|"
-    "function |function |constructor |"
-    "constructor (the implicit default constructor)|"
-    "constructor (the implicit copy constructor)|"
-    "constructor (the implicit move constructor)|"
-    "function (the implicit copy assignment operator)|"
-    "function (the implicit move assignment operator)|"
-    "inherited constructor|"
-    "inherited constructor }0%1 "
+    "%sub{select_ovl_template_kind}0%1 "
     "not viable: cannot convert initializer list argument to %3">;
 def note_ovl_candidate_bad_overload : Note<"candidate "
-    "%select{function|function|constructor|"
-    "function |function |constructor |"
-    "constructor (the implicit default constructor)|"
-    "constructor (the implicit copy constructor)|"
-    "constructor (the implicit move constructor)|"
-    "function (the implicit copy assignment operator)|"
-    "function (the implicit move assignment operator)|"
-    "inherited constructor|"
-    "inherited constructor }0%1"
+    "%sub{select_ovl_template_kind}0%1"
     " not viable: no overload of %3 matching %2 for %ordinal4 argument">;
 def note_ovl_candidate_bad_conv : Note<"candidate "
-    "%select{function|function|constructor|"
-    "function |function |constructor |"
-    "constructor (the implicit default constructor)|"
-    "constructor (the implicit copy constructor)|"
-    "constructor (the implicit move constructor)|"
-    "function (the implicit copy assignment operator)|"
-    "function (the implicit move assignment operator)|"
-    "inherited constructor|"
-    "inherited constructor }0%1"
+    "%sub{select_ovl_template_kind}0%1"
     " not viable: no known conversion "
     "%diff{from $ to $|from argument type to parameter type}2,3 for "
     "%select{%ordinal5 argument|object argument}4"
     "%select{|; dereference the argument with *|"
     "; take the address of the argument with &|"
     "; remove *|"
     "; remove &}6">;
 def note_ovl_candidate_bad_arc_conv : Note<"candidate "
-    "%select{function|function|constructor|"
-    "function |function |constructor |"
-    "constructor (the implicit default constructor)|"
-    "constructor (the implicit copy constructor)|"
-    "constructor (the implicit move constructor)|"
-    "function (the implicit copy assignment operator)|"
-    "function (the implicit move assignment operator)|"
-    "inherited constructor|"
-    "inherited constructor }0%1"
+    "%sub{select_ovl_template_kind}0%1"
     " not viable: cannot implicitly convert argument "
     "%diff{of type $ to $|type to parameter type}2,3 for "
     "%select{%ordinal5 argument|object argument}4 under ARC">;
 def note_ovl_candidate_bad_lvalue : Note<"candidate "
-    "%select{function|function|constructor|"
-    "function |function |constructor |"
-    "constructor (the implicit default constructor)|"
-    "constructor (the implicit copy constructor)|"
-    "constructor (the implicit move constructor)|"
-    "function (the implicit copy assignment operator)|"
-    "function (the implicit move assignment operator)|"
-    "inherited constructor|"
-    "inherited constructor }0%1"
+    "%sub{select_ovl_template_kind}0%1"
     " not viable: expects an l-value for "
     "%select{%ordinal3 argument|object argument}2">;
 def note_ovl_candidate_bad_addrspace : Note<"candidate "
-    "%select{function|function|constructor|"
-    "function |function |constructor |"
-    "constructor (the implicit default constructor)|"
-    "constructor (the implicit copy constructor)|"
-    "constructor (the implicit move constructor)|"
-    "function (the implicit copy assignment operator)|"
-    "function (the implicit move assignment operator)|"
-    "inherited constructor|"
-    "inherited constructor }0%1 not viable: "
+    "%sub{select_ovl_template_kind}0%1 not viable: "
     "%select{%ordinal6|'this'}5 argument (%2) is in "
     "address space %3, but parameter must be in address space %4">;
 def note_ovl_candidate_bad_gc : Note<"candidate "
-    "%select{function|function|constructor|"
-    "function |function |constructor |"
-    "constructor (the implicit default constructor)|"
-    "constructor (the implicit copy constructor)|"
-    "constructor (the implicit move constructor)|"
-    "function (the implicit copy assignment operator)|"
-    "function (the implicit move assignment operator)|"
-    "inherited constructor|"
-    "inherited constructor }0%1 not viable: "
+    "%sub{select_ovl_template_kind}0%1 not viable: "
     "%select{%ordinal6|'this'}5 argument (%2) has %select{no|__weak|__strong}3 "
     "ownership, but parameter has %select{no|__weak|__strong}4 ownership">;
 def note_ovl_candidate_bad_ownership : Note<"candidate "
-    "%select{function|function|constructor|"
-    "function |function |constructor |"
-    "constructor (the implicit default constructor)|"
-    "constructor (the implicit copy constructor)|"
-    "constructor (the implicit move constructor)|"
-    "function (the implicit copy assignment operator)|"
-    "function (the implicit move assignment operator)|"
-    "inherited constructor|"
-    "inherited constructor }0%1 not viable: "
+    "%sub{select_ovl_template_kind}0%1 not viable: "
     "%select{%ordinal6|'this'}5 argument (%2) has "
     "%select{no|__unsafe_unretained|__strong|__weak|__autoreleasing}3 ownership,"
     " but parameter has %select{no|__unsafe_unretained|__strong|__weak|"
     "__autoreleasing}4 ownership">;
 def note_ovl_candidate_bad_cvr_this : Note<"candidate "
     "%select{|function|||function|||||"
     "function (the implicit copy assignment operator)|"
     "function (the implicit move assignment operator)||}0 not viable: "
     "'this' argument has type %2, but method is not marked "
     "%select{const|restrict|const or restrict|volatile|const or volatile|"
     "volatile or restrict|const, volatile, or restrict}3">;
 def note_ovl_candidate_bad_cvr : Note<"candidate "
-    "%select{function|function|constructor|"
-    "function |function |constructor |"
-    "constructor (the implicit default constructor)|"
-    "constructor (the implicit copy constructor)|"
-    "constructor (the implicit move constructor)|"
-    "function (the implicit copy assignment operator)|"
-    "function (the implicit move assignment operator)|"
-    "inherited constructor|"
-    "inherited constructor }0%1 not viable: "
+    "%sub{select_ovl_template_kind}0%1 not viable: "
     "%ordinal4 argument (%2) would lose "
     "%select{const|restrict|const and restrict|volatile|const and volatile|"
     "volatile and restrict|const, volatile, and restrict}3 qualifier"
     "%select{||s||s|s|s}3">;
 def note_ovl_candidate_bad_unaligned : Note<"candidate "
-    "%select{function|function|constructor|"
-    "function |function |constructor |"
-    "constructor (the implicit default constructor)|"
-    "constructor (the implicit copy constructor)|"
-    "constructor (the implicit move constructor)|"
-    "function (the implicit copy assignment operator)|"
-    "function (the implicit move assignment operator)|"
-    "inherited constructor|"
-    "inherited constructor }0%1 not viable: "
+    "%sub{select_ovl_template_kind}0%1 not viable: "
     "%ordinal4 argument (%2) would lose __unaligned qualifier">;
 def note_ovl_candidate_bad_base_to_derived_conv : Note<"candidate "
-    "%select{function|function|constructor|"
-    "function |function |constructor |"
-    "constructor (the implicit default constructor)|"
-    "constructor (the implicit copy constructor)|"
-    "constructor (the implicit move constructor)|"
-    "function (the implicit copy assignment operator)|"
-    "function (the implicit move assignment operator)|"
-    "inherited constructor|"
-    "inherited constructor }0%1 not viable: "
+    "%sub{select_ovl_template_kind}0%1 not viable: "
     "cannot %select{convert from|convert from|bind}2 "
     "%select{base class pointer|superclass|base class object of type}2 %3 to "
     "%select{derived class pointer|subclass|derived class reference}2 %4 for "
     "%ordinal5 argument">;
 def note_ovl_candidate_bad_target : Note<
-    "candidate %select{function|function|constructor|"
-    "function|function|constructor|"
-    "constructor (the implicit default constructor)|"
-    "constructor (the implicit copy constructor)|"
-    "constructor (the implicit move constructor)|"
-    "function (the implicit copy assignment operator)|"
-    "function (the implicit move assignment operator)|"
-    "inherited constructor|"
-    "inherited constructor}0 not viable: "
+    "candidate %sub{select_ovl_candidate_kind}0 not viable: "
     "call to "
     "%select{__device__|__global__|__host__|__host__ __device__|invalid}1 function from"
     " %select{__device__|__global__|__host__|__host__ __device__|invalid}2 function">;
 def note_implicit_member_target_infer_collision : Note<
     "implicit %select{"
     "default constructor|"
     "copy constructor|"
     "move constructor|"

 
 // C++11 explicit conversion operators
 def ext_explicit_conversion_functions : ExtWarn<
   "explicit conversion functions are a C++11 extension">, InGroup<CXX11>;
 def warn_cxx98_compat_explicit_conversion_functions : Warning<
   "explicit conversion functions are incompatible with C++98">,
   InGroup<CXX98Compat>, DefaultIgnore;
 
+def select_special_member : TextSubstitution<
+  "%select{default constructor|copy constructor|move constructor|"
+  "copy assignment operator|move assignment operator|destructor}0">;
+
 // C++11 defaulted functions
 def err_defaulted_special_member_params : Error<
   "an explicitly-defaulted %select{|copy |move }0constructor cannot "
   "have default arguments">;
 def err_defaulted_special_member_variadic : Error<
   "an explicitly-defaulted %select{|copy |move }0constructor cannot "
   "be variadic">;
 def err_defaulted_special_member_return_type : Error<
   "explicitly-defaulted %select{copy|move}0 assignment operator must "
   "return %1">;
 def err_defaulted_special_member_quals : Error<
   "an explicitly-defaulted %select{copy|move}0 assignment operator may not "
   "have 'const'%select{, 'constexpr'|}1 or 'volatile' qualifiers">;
 def err_defaulted_special_member_volatile_param : Error<
-  "the parameter for an explicitly-defaulted %select{<<ERROR>>|"
-  "copy constructor|move constructor|copy assignment operator|"
-  "move assignment operator|<<ERROR>>}0 may not be volatile">;
+  "the parameter for an explicitly-defaulted %sub{select_special_member}0 "
+  "may not be volatile">;
 def err_defaulted_special_member_move_const_param : Error<
   "the parameter for an explicitly-defaulted move "
   "%select{constructor|assignment operator}0 may not be const">;
 def err_defaulted_special_member_copy_const_param : Error<
   "the parameter for this explicitly-defaulted copy "
   "%select{constructor|assignment operator}0 is const, but a member or base "
   "requires it to be non-const">;
 def err_defaulted_copy_assign_not_ref : Error<
   "the parameter for an explicitly-defaulted copy assignment operator must be an "
   "lvalue reference type">;
 def err_incorrect_defaulted_exception_spec : Error<
-  "exception specification of explicitly defaulted %select{default constructor|"
-  "copy constructor|move constructor|copy assignment operator|move assignment "
-  "operator|destructor}0 does not match the "
-  "calculated one">;
+  "exception specification of explicitly defaulted %sub{select_special_member}0 "
+  "does not match the calculated one">;
 def err_incorrect_defaulted_constexpr : Error<
-  "defaulted definition of %select{default constructor|copy constructor|"
-  "move constructor|copy assignment operator|move assignment operator}0 "
+  "defaulted definition of %sub{select_special_member}0 "
   "is not constexpr">;
 def err_out_of_line_default_deletes : Error<
-  "defaulting this %select{default constructor|copy constructor|move "
-  "constructor|copy assignment operator|move assignment operator|destructor}0 "
+  "defaulting this %sub{select_special_member}0 "
   "would delete it after its first declaration">;
 def warn_vbase_moved_multiple_times : Warning<
   "defaulted move assignment operator of %0 will move assign virtual base "
   "class %1 multiple times">, InGroup<DiagGroup<"multiple-move-vbase">>;
 def note_vbase_moved_here : Note<
   "%select{%1 is a virtual base class of base class %2 declared here|"
   "virtual base class %1 declared here}0">;
 

test/TableGen/DiagnosticBase.inc

-// Define the diagnostic mappings.
-class DiagMapping;
-def MAP_IGNORE  : DiagMapping;
-def MAP_WARNING : DiagMapping;
-def MAP_ERROR   : DiagMapping;
-def MAP_FATAL   : DiagMapping;
+//===--- Diagnostic.td - C Language Family Diagnostic Handling ------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+//
+//  This file defines the TableGen core definitions for the diagnostics
+//  and diagnostic control.
+//
+//===----------------------------------------------------------------------===//
+
+// See the Internals Manual, section The Diagnostics Subsystem for an overview.
+
+// Define the diagnostic severities.
+class Severity<string N> {
+  string Name = N;
+}
+def SEV_Ignored : Severity<"Ignored">;
+def SEV_Remark  : Severity<"Remark">;
+def SEV_Warning : Severity<"Warning">;
+def SEV_Error   : Severity<"Error">;
+def SEV_Fatal   : Severity<"Fatal">;
 
 // Define the diagnostic classes.
 class DiagClass;
 def CLASS_NOTE      : DiagClass;
+def CLASS_REMARK    : DiagClass;
 def CLASS_WARNING   : DiagClass;
 def CLASS_EXTENSION : DiagClass;
 def CLASS_ERROR     : DiagClass;
 
+// Responses to a diagnostic in a SFINAE context.
+class SFINAEResponse;
+def SFINAE_SubstitutionFailure : SFINAEResponse;
+def SFINAE_Suppress            : SFINAEResponse;
+def SFINAE_Report              : SFINAEResponse;
+def SFINAE_AccessControl       : SFINAEResponse;
+
+// Textual substitutions which may be performed on the text of diagnostics
+class TextSubstitution<string Text> {
+  string Substitution = Text;
+  // TODO: These are only here to allow substitutions to be declared inline with
+  // diagnostics
+  string Component = "";
+  string CategoryName = "";
+}
+
+// Diagnostic Categories.  These can be applied to groups or individual
+// diagnostics to specify a category.
+class DiagCategory<string Name> {
+  string CategoryName = Name;
+}
+
+// Diagnostic Groups.
 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>; }
+
+include "DiagnosticDocs.inc"
 
 // All diagnostics emitted by the compiler are an indirect subclass of this.
-class Diagnostic<string text, DiagClass DC, DiagMapping defaultmapping> {
+class Diagnostic<string text, DiagClass DC, Severity defaultmapping> {
+  /// Component is specified by the file with a big let directive.
+  string         Component = ?;
   string         Text = text;
   DiagClass      Class = DC;
-  DiagMapping DefaultMapping = defaultmapping;
+  SFINAEResponse SFINAE = SFINAE_Suppress;
+  bit            AccessControl = 0;
+  bit            WarningNoWerror = 0;
+  bit            ShowInSystemHeader = 0;
+  Severity       DefaultSeverity = defaultmapping;
   DiagGroup      Group;
   string         CategoryName = "";
 }
 
-class Error<string str>     : Diagnostic<str, CLASS_ERROR, MAP_ERROR>;
-class Warning<string str>   : Diagnostic<str, CLASS_WARNING, MAP_WARNING>;
-class Extension<string str> : Diagnostic<str, CLASS_EXTENSION, MAP_IGNORE>;
-class ExtWarn<string str>   : Diagnostic<str, CLASS_EXTENSION, MAP_WARNING>;
-class Note<string str>      : Diagnostic<str, CLASS_NOTE, MAP_FATAL/*ignored*/>;
+class SFINAEFailure {
+  SFINAEResponse SFINAE = SFINAE_SubstitutionFailure;
+}
+class NoSFINAE {
+  SFINAEResponse SFINAE = SFINAE_Report;
+}
+class AccessControl {
+  SFINAEResponse SFINAE = SFINAE_AccessControl;
+}
+
+class ShowInSystemHeader {
+  bit ShowInSystemHeader = 1;
+}
+
+class SuppressInSystemHeader {
+  bit ShowInSystemHeader = 0;
+}
+
+// FIXME: ExtWarn and Extension should also be SFINAEFailure by default.
+class Error<string str>     : Diagnostic<str, CLASS_ERROR, SEV_Error>, 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>;
+// 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>;
+// 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>;
+// ExtWarns are warnings about accepted language extensions.
+// ExtWarn warnings are default-on.
+class ExtWarn<string str>   : Diagnostic<str, CLASS_EXTENSION, SEV_Warning>;
+// Notes can provide supplementary information on errors, warnings, and remarks.
+class Note<string str>      : Diagnostic<str, CLASS_NOTE, SEV_Fatal/*ignored*/>;
+
+
+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; }

test/TableGen/DiagnosticDocs.inc

+
+def GlobalDocumentation {
+  code Intro =[{..
+  -------------------------------------------------------------------
+  NOTE: This file is automatically generated by running clang-tblgen
+  -gen-diag-docs. Do not edit this file by hand!!
+  -------------------------------------------------------------------
+
+.. Add custom CSS to output. FIXME: This should be put into <head> rather
+   than the start of <body>.
+.. raw:: html
+
+    <style>
+    table.docutils {
+      width: 1px;
+    }
+    table.docutils td {
+      border: none;
+      padding: 0 0 0 0.2em;
+      vertical-align: middle;
+      white-space: nowrap;
+      width: 1px;
+      font-family: monospace;
+    }
+    table.docutils tr + tr {
+      border-top: 0.2em solid #aaa;
+    }
+    .error {
+      font-family: monospace;
+      font-weight: bold;
+      color: #c00;
+    }
+    .warning {
+      font-family: monospace;
+      font-weight: bold;
+      color: #80a;
+    }
+    .remark {
+      font-family: monospace;
+      font-weight: bold;
+      color: #00c;
+    }
+    .diagtext {
+      font-family: monospace;
+      font-weight: bold;
+    }
+    </style>
+
+.. FIXME: rST doesn't support formatting this, so we format all <td> elements
+          as monospace font face instead.
+.. |nbsp| unicode:: 0xA0
+   :trim:
+
+.. Roles generated by clang-tblgen.
+.. role:: error
+.. role:: warning
+.. role:: remark
+.. role:: diagtext
+.. role:: placeholder(emphasis)
+
+=========================
+Diagnostic flags in Clang
+=========================
+.. contents::
+   :local:
+
+Introduction
+============
+
+This page lists the diagnostic flags currently supported by Clang.
+
+Diagnostic flags
+================
+}];
+}

test/TableGen/emit-diag-docs.td

+// RUN: clang-tblgen -gen-diag-docs -I%S %s -o - 2>&1 | \
+// RUN:    FileCheck --strict-whitespace %s
+include "DiagnosticBase.inc"
+
+def MyGroup : DiagGroup<"MyGroupName">;
+
+def MyKinds : TextSubstitution<"%select{food|forests}0">;
+def MyGoodBad : TextSubstitution<"%select{good|bad}0">;
+def MySubNested : TextSubstitution<"%sub{MyGoodBad}1 %sub{MyKinds}2 are %sub{MyGoodBad}1 according to %0">;
+
+// CHECK: -WMyGroupName
+// CHECK: **Diagnostic text:**
+
+let Group = MyGroup in {
+
+// CHECK:      |:warning:`warning:` |nbsp| :diagtext:`this is my diff text`|
+// CHECK-NEXT: +-----------------------------------------------------------+
+def CheckDiff : Warning<"%diff{$ is not $|this is my diff text}0,1">;
+
+
+// CHECK:      |:warning:`warning:` |nbsp| :placeholder:`A` |nbsp| :diagtext:`is my modifier test` |nbsp| :placeholder:`B`|
+// CHECK-NEXT: +----------------------------------------------------------------------------------------------------------+
+def CheckModifier : Warning<"%0 is my modifier test %1">;
+
+
+// CHECK:      |:warning:`warning:` |nbsp| :diagtext:`This is the` |nbsp| :placeholder:`A` |nbsp| :diagtext:`test I've written`|
+// CHECK-NEXT: +---------------------------------------------------------------------------------------------------------------+
+def CheckOrdinal : Warning<"This is the %ordinal0 test I've written">;
+
+
+// CHECK:      |:warning:`warning:` |nbsp| :diagtext:`I wrote` |nbsp| |+-------------------------------+| |nbsp| :diagtext:`tests`|
+// CHECK-NEXT: |                                                      ||:diagtext:`:no`                ||                         |
+// CHECK-NEXT: |                                                      |+-------------------------------+|                         |
+// CHECK-NEXT: |                                                      ||:diagtext:`:one`               ||                         |
+// CHECK-NEXT: |                                                      |+-------------------------------+|                         |
+// CHECK-NEXT: |                                                      ||+-----------------------------+||                         |
+// CHECK-NEXT: |                                                      |||:diagtext:`:`:placeholder:`A`|||                         |
+// CHECK-NEXT: |                                                      ||+-----------------------------+||                         |
+// CHECK-NEXT: |                                                      |+-------------------------------+|                         |
+// CHECK-NEXT: +------------------------------------------------------+---------------------------------+-------------------------+
+def CheckPlural : Warning<"I wrote %plural{0:no|1:one|:%0}0 tests">;
+
+
+// CHECK:      |:warning:`warning:` |nbsp| :diagtext:`bad type` |nbsp| :placeholder:`A`|
+// CHECK-NEXT: +-----------------------------------------------------------------------+
+def CheckQ : Warning<"bad type %q0">;
+
+
+// CHECK:      |:warning:`warning:` |nbsp| :diagtext:`My test`|+-------------+| |nbsp| :diagtext:`are the best!`|
+// CHECK-NEXT: |                                              ||             ||                                 |
+// CHECK-NEXT: |                                              |+-------------+|                                 |
+// CHECK-NEXT: |                                              ||:diagtext:`s`||                                 |
+// CHECK-NEXT: |                                              |+-------------+|                                 |
+// CHECK-NEXT: +----------------------------------------------+---------------+---------------------------------+
+def CheckS : Warning<"My test%s0 are the best!">;
+
+
+// CHECK:      |:warning:`warning:` |nbsp| :diagtext:`this is my select test:` |nbsp| |+---------------+|
+// CHECK-NEXT: |                                                                      ||:diagtext:`one`||
+// CHECK-NEXT: |                                                                      |+---------------+|
+// CHECK-NEXT: |                                                                      ||:diagtext:`two`||
+// CHECK-NEXT: |                                                                      |+---------------+|
+// CHECK-NEXT: +----------------------------------------------------------------------+-----------------+
+def CheckSelect : Warning<"this is my select test: %select{one|two}0 and it is %select{good|bad}1">;
+
+
+// CHECK:      +-------------------------------------------------------+------------------+--------+---------------------+-------------------------------+------------------+--------------------------------------------------------+
+// CHECK-NEXT: |:warning:`warning:` |nbsp| :diagtext:`They say` |nbsp| |+----------------+| |nbsp| |+-------------------+| |nbsp| :diagtext:`are` |nbsp| |+----------------+| |nbsp| :diagtext:`according to` |nbsp| :placeholder:`D`|
+// CHECK-NEXT: |                                                       ||:diagtext:`good`||        ||:diagtext:`food`   ||                               ||:diagtext:`good`||                                                        |
+// CHECK-NEXT: |                                                       |+----------------+|        |+-------------------+|                               |+----------------+|                                                        |
+// CHECK-NEXT: |                                                       ||:diagtext:`bad` ||        ||:diagtext:`forests`||                               ||:diagtext:`bad` ||                                                        |
+// CHECK-NEXT: |                                                       |+----------------+|        |+-------------------+|                               |+----------------+|                                                        |
+// CHECK-NEXT: +-------------------------------------------------------+------------------+--------+---------------------+-------------------------------+------------------+--------------------------------------------------------+
+def CheckSubstitution : Warning<"They say %sub{MySubNested}3,1,0">;
+
+
+// CHECK:      |:warning:`warning:` |nbsp| :diagtext:`this is my warning text`|
+// CHECK-NEXT: +--------------------------------------------------------------+
+def CheckText : Warning<"this is my warning text">;
+
+}

test/TableGen/text-substitution.td

+// RUN: clang-tblgen -gen-clang-diags-defs -I%S %s -o - 2>&1 | \
+// RUN:    FileCheck --strict-whitespace %s
+include "DiagnosticBase.inc"
+
+def DocumentedGroup : DiagGroup<"DocumentedGroup">;
+
+def select_sub : TextSubstitution<"%2 %select{%1}0">;
+
+// CHECK: AHHH
+def AGGG : Warning<"%select{one|two}0 is OK">, InGroup<DocumentedGroup>;
+def sub_diag : Note<"%sub{select_sub}0">;

test/lit.cfg.py

 
 # For each occurrence of a clang tool name, replace it with the full path to
 # the build directory holding that tool.  We explicitly specify the directories
 # to search to ensure that we get the tools just built and not some random
 # tools that might happen to be in the user's PATH.
 tool_dirs = [config.clang_tools_dir, config.llvm_tools_dir]
 
 tools = [
-    'c-index-test', 'clang-check', 'clang-diff', 'clang-format', 'opt',
+    'c-index-test', 'clang-check', 'clang-diff', 'clang-format', 'clang-tblgen',
+    'opt',
     ToolSubst('%clang_func_map', command=FindTool(
         'clang-func-mapping'), unresolved='ignore'),
 ]
 
 if config.clang_examples:
     config.available_features.add('examples')
     tools.append('clang-interpreter')
 

utils/TableGen/ClangDiagnosticsEmitter.cpp

 //=- ClangDiagnosticsEmitter.cpp - Generate Clang diagnostics tables -*- C++ -*-
 //
 //                     The LLVM Compiler Infrastructure
 //
 // This file is distributed under the University of Illinois Open Source
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
 //
 // These tablegen backends emit Clang diagnostics tables.
 //
 //===----------------------------------------------------------------------===//
 
 #include "llvm/ADT/DenseSet.h"
 #include "llvm/ADT/Optional.h"
 #include "llvm/ADT/PointerUnion.h"
+#include "llvm/ADT/STLExtras.h"
 #include "llvm/ADT/SmallPtrSet.h"
 #include "llvm/ADT/SmallString.h"
 #include "llvm/ADT/SmallVector.h"
 #include "llvm/ADT/StringMap.h"
-#include "llvm/ADT/STLExtras.h"
 #include "llvm/ADT/Twine.h"
+#include "llvm/Support/Casting.h"
+#include "llvm/Support/Regex.h"
 #include "llvm/TableGen/Error.h"
 #include "llvm/TableGen/Record.h"
 #include "llvm/TableGen/StringToOffsetTable.h"
 #include "llvm/TableGen/TableGenBackend.h"
 #include <algorithm>
 #include <cctype>
 #include <functional>
 #include <map>
for (unsigned i = 0, ei = DiagGroups.size(); i != ei; ++i) {
     if (RecordVec *V = GroupsInPedantic.dyn_cast<RecordVec*>())
       V->push_back(Group);
     else {
       GroupsInPedantic.get<RecordSet*>()->insert(Group);
     }
   }
 }
 
+namespace {
+enum PieceKind {
+  MultiPieceClass,
+  TextPieceClass,
+  PlaceholderPieceClass,
+  SelectPieceClass,
+  DiffPieceClass,
+  SubstitutionPieceClass,
+};
+
+struct DiagText;
+
+enum ModifierType {
+  MT_Unknown,
+  MT_Placeholder,
+  MT_Select,
+  MT_Sub,
+  MT_Plural,
+  MT_Diff,
+  MT_Ordinal,
+  MT_S,
+  MT_Q,
+  MT_ObjCClass,
+  MT_ObjCInstance,
+};
+
+static StringRef getModifierName(ModifierType MT) {
+  switch (MT) {
+  case MT_Select:
+    return "select";
+  case MT_Sub:
+    return "sub";
+  case MT_Diff:
+    return "diff";
+  case MT_Plural:
+    return "plural";
+  case MT_Ordinal:
+    return "ordinal";
+  case MT_S:
+    return "s";
+  case MT_Q:
+    return "q";
+  case MT_Placeholder:
+    return "";
+  case MT_ObjCClass:
+    return "objcclass";
+  case MT_ObjCInstance:
+    return "objcinstance";
+  case MT_Unknown:
+    return "<<UNKNOWN>>";
+  }
+}
+
+struct Piece {
+  // This type and its derived classes are move-only.
+  Piece(PieceKind Kind) : ClassKind(Kind) {}
+  Piece(Piece const &O) = delete;
+  Piece &operator=(Piece const &) = delete;
+  virtual ~Piece() {}
+
+  PieceKind getPieceClass() const { return ClassKind; }
+  static bool classof(const Piece *) { return true; }
+
+private:
+  PieceKind ClassKind;
+};
+
+struct MultiPiece : Piece {
+  MultiPiece() : Piece(MultiPieceClass) {}
+  MultiPiece(std::vector<Piece *> Pieces)
+      : Piece(MultiPieceClass), Pieces(std::move(Pieces)) {}
+
+  std::vector<Piece *> Pieces;
+
+  static bool classof(const Piece *P) {
+    return P->getPieceClass() == MultiPieceClass;
+  }
+};
+
+struct TextPiece : Piece {
+  StringRef Role;
+  std::string Text;
+  TextPiece(StringRef Text, StringRef Role = "")
+      : Piece(TextPieceClass), Role(Role), Text(Text.str()) {}
+
+  static bool classof(const Piece *P) {
+    return P->getPieceClass() == TextPieceClass;
+  }
+};
+
+struct PlaceholderPiece : Piece {
+  ModifierType Kind;
+  int Index;
+  PlaceholderPiece(ModifierType Kind, int Index)
+      : Piece(PlaceholderPieceClass), Kind(Kind), Index(Index) {}
+
+  static bool classof(const Piece *P) {
+    return P->getPieceClass() == PlaceholderPieceClass;
+  }
+};
+
+struct SelectPiece : Piece {
+  SelectPiece(ModifierType Kind) : Piece(SelectPieceClass), Kind(Kind) {}
+
+  ModifierType Kind;
+  std::vector<Piece *> Options;
+  unsigned Index;
+
+  static bool classof(const Piece *P) {
+    return P->getPieceClass() == SelectPieceClass;
+  }
+};
+
+struct DiffPiece : Piece {
+  DiffPiece() : Piece(DiffPieceClass) {}
+
+  Piece *Options[2] = {};
+  unsigned Indexes[2] = {};
+
+  static bool classof(const Piece *P) {
+    return P->getPieceClass() == DiffPieceClass;
+  }
+};
+
+struct SubstitutionPiece : Piece {
+  SubstitutionPiece() : Piece(SubstitutionPieceClass) {}
+
+  std::string Name;
+  std::vector<unsigned> Modifiers;
+  Piece *Substitution = nullptr;
+
+  static bool classof(const Piece *P) {
+    return P->getPieceClass() == SubstitutionPieceClass;
+  }
+};
+
+/// Diagnostic text, parsed into pieces.
+struct DiagText {
+private:
+  friend struct DiagnosticTextBuilder;
+  std::vector<Piece *> AllocatedPieces;
+  Piece *Root = nullptr;
+
+  template <class T, class... Args> T *create(Args &&... args) {
+    static_assert(std::is_base_of<Piece, T>::value, "must be piece");
+    T *Mem = new T(std::forward<Args>(args)...);
+    AllocatedPieces.push_back(Mem);
+    return Mem;
+  }
+
+  DiagText() {}
+  Piece *parseDiagText(StringRef &Text, bool Nested = false);
+
+  DiagText(StringRef Text) : Root(nullptr) { Root = parseDiagText(Text); }
+
+  DiagText(StringRef Kind, StringRef Text) : DiagText(Text) {
+    TextPiece *Prefix = create<TextPiece>(Kind, Kind);
+    Prefix->Text += ": ";
+    auto *MP = dyn_cast<MultiPiece>(Root);
+    if (!MP) {
+      MP = create<MultiPiece>();
+      MP->Pieces.push_back(Root);
+      Root = MP;
+    }
+    MP->Pieces.insert(MP->Pieces.begin(), Prefix);
+  }
+
+public:
+  DiagText(DiagText &&O) noexcept
+      : AllocatedPieces(std::move(O.AllocatedPieces)), Root(O.Root) {
+    O.Root = nullptr;
+  }
+
+  Piece *getRoot() const { return Root; }
+
+  ~DiagText() {
+    for (Piece *P : AllocatedPieces)
+      delete P;
+  }
+};
+
+struct DiagnosticTextBuilder {
+  DiagnosticTextBuilder(DiagnosticTextBuilder const &) = delete;
+  DiagnosticTextBuilder &operator=(DiagnosticTextBuilder const &) = delete;
+
+  DiagnosticTextBuilder(RecordKeeper &Records) {
+    for (auto *S : Records.getAllDerivedDefinitions("TextSubstitution"))
+      Substitutions.try_emplace(S->getName(),
+                                DiagText(S->getValueAsString("Substitution")));
+  }
+
+  std::vector<std::string> buildForDocumentation(StringRef Role,
+                                                 const Record *R);
+  std::string buildForDiagnostic(const Record *R);
+
+private:
+  template <class Derived> friend struct DiagTextVisitor;
+  const Record *EvaluatingRecord = nullptr;
+  StringMap<DiagText> Substitutions;
+};
+
+template <class Derived> struct DiagTextVisitor {
+  using ModifierMappingsType = Optional<std::vector<unsigned>>;
+
+private:
+  Derived &getDerived() { return static_cast<Derived &>(*this); }
+
+public:
+  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.getRoot();
+  }
+
+  std::vector<unsigned>
+  getSubstitutionMappings(SubstitutionPiece *P,
+                          const ModifierMappingsType &Mappings) const {
+    std::vector<unsigned> NewMappings;
+    for (unsigned Idx : P->Modifiers)
+      NewMappings.push_back(mapIndex(Idx, Mappings));
+    return NewMappings;
+  }
+
+  struct SubstitutionContext {
+    SubstitutionContext(DiagTextVisitor &Visitor, SubstitutionPiece *P)
+        : Visitor(Visitor) {
+      Substitution = Visitor.getSubstitution(P);
+      OldMappings = std::move(Visitor.ModifierMappings);
+      std::vector<unsigned> NewMappings =
+          Visitor.getSubstitutionMappings(P, OldMappings);
+      Visitor.ModifierMappings = std::move(NewMappings);
+    }
+
+    ~SubstitutionContext() {
+      Visitor.ModifierMappings = std::move(OldMappings);
+    }
+
+  private:
+    DiagTextVisitor &Visitor;
+    Optional<std::vector<unsigned>> OldMappings;
+
+  public:
+    Piece *Substitution;
+  };
+
+public:
+  DiagTextVisitor(DiagnosticTextBuilder &Builder)
+      : Builder(Builder), Substitutions(Builder.Substitutions) {}
+
+  void Visit(Piece *P) {
+    switch (P->getPieceClass()) {
+#define CASE(T)                                                                \
+  case T##PieceClass:                                                          \
+    return getDerived().Visit##T(static_cast<T##Piece *>(P))
+      CASE(Multi);
+      CASE(Text);
+      CASE(Placeholder);
+      CASE(Select);
+      CASE(Diff);
+      CASE(Substitution);
+#undef CASE
+    }
+  }
+
+  void VisitSubstitution(SubstitutionPiece *P) {
+    SubstitutionContext Guard(*this, P);
+    Visit(Guard.Substitution);
+  }
+
+  unsigned mapIndex(unsigned Idx,
+                    ModifierMappingsType const &ModifierMappings) const {
+    if (!ModifierMappings)
+      return Idx;
+    if (ModifierMappings->size() <= Idx)
+      PrintFatalError("Modifier value '" + std::to_string(Idx) +
+                      "' is not valid for this mapping (has " +
+                      std::to_string(ModifierMappings->size()) + " mappings)");
+    return (*ModifierMappings)[Idx];
+  }
+  unsigned mapIndex(unsigned Idx) const {
+    return mapIndex(Idx, ModifierMappings);
+  }
+
+protected:
+  DiagnosticTextBuilder &Builder;
+  StringMap<DiagText> &Substitutions;
+  ModifierMappingsType ModifierMappings;
+};
+
+void escapeRST(StringRef Str, std::string &Out) {
+  for (auto K : Str) {
+    if (StringRef("`*|_[]\\").count(K))
+      Out.push_back('\\');
+    Out.push_back(K);
+  }
+}
+
+template <typename It> void padToSameLength(It Begin, It End) {
+  size_t Width = 0;
+  for (It I = Begin; I != End; ++I)
+    Width = std::max(Width, I->size());
+  for (It I = Begin; I != End; ++I)
+    (*I) += std::string(Width - I->size(), ' ');
+}
+
+template <typename It> void makeTableRows(It Begin, It End) {
+  if (Begin == End)
+    return;
+  padToSameLength(Begin, End);
+  for (It I = Begin; I != End; ++I)
+    *I = "|" + *I + "|";
+}
+
+void makeRowSeparator(std::string &Str) {
+  for (char &K : Str)
+    K = (K == '|' ? '+' : '-');
+}
+
+struct DiagTextDocPrinter : DiagTextVisitor<DiagTextDocPrinter> {
+  using BaseTy = DiagTextVisitor<DiagTextDocPrinter>;
+  DiagTextDocPrinter(DiagnosticTextBuilder &Builder,
+                     std::vector<std::string> &RST)
+      : BaseTy(Builder), RST(RST) {}
+
+  void gatherNodes(
+      Piece *OrigP, const ModifierMappingsType &CurrentMappings,
+      std::vector<std::pair<Piece *, ModifierMappingsType>> &Pieces) const {
+    if (auto *Sub = dyn_cast<SubstitutionPiece>(OrigP)) {
+      ModifierMappingsType NewMappings =
+          getSubstitutionMappings(Sub, CurrentMappings);
+      return gatherNodes(getSubstitution(Sub), NewMappings, Pieces);
+    }
+    if (auto *MD = dyn_cast<MultiPiece>(OrigP)) {
+      for (auto *Node : MD->Pieces)
+        gatherNodes(Node, CurrentMappings, Pieces);
+      return;
+    }
+    Pieces.push_back(std::make_pair(OrigP, CurrentMappings));
+  }
+
+  void VisitMulti(MultiPiece *P) {
+    if (P->Pieces.empty()) {
+      RST.push_back("");
+      return;
+    }
+
+    if (P->Pieces.size() == 1)
+      return Visit(P->Pieces[0]);
+
+    // Flatten the list of nodes, replacing any substitution pieces with the
+    // recursively flattened substituted node.
+    std::vector<std::pair<Piece *, ModifierMappingsType>> Pieces;
+    gatherNodes(P, ModifierMappings, Pieces);
+
+    std::string EmptyLinePrefix;
+    size_t Start = RST.size();
+    bool HasMultipleLines = true;
+    for (auto NodePair : Pieces) {
+      std::vector<std::string> Lines;
+      DiagTextDocPrinter Visitor{Builder, Lines};
+      Visitor.ModifierMappings = NodePair.second;
+      Visitor.Visit(NodePair.first);
+
+      if (Lines.empty())
+        continue;
+
+      // We need a vertical separator if either this or the previous piece is a
+      // multi-line piece, or this is the last piece.
+      const char *Separator = (Lines.size() > 1 || HasMultipleLines) ? "|" : "";
+      HasMultipleLines = Lines.size() > 1;
+
+      if (Start + Lines.size() > RST.size())
+        RST.resize(Start + Lines.size(), EmptyLinePrefix);
+
+      padToSameLength(Lines.begin(), Lines.end());
+      for (size_t I = 0; I != Lines.size(); ++I)
+        RST[Start + I] += Separator + Lines[I];
+      std::string Empty(Lines[0].size(), ' ');
+      for (size_t I = Start + Lines.size(); I != RST.size(); ++I)
+        RST[I] += Separator + Empty;
+      EmptyLinePrefix += Separator + Empty;
+    }
+    for (size_t I = Start; I != RST.size(); ++I)
+      RST[I] += "|";
+    EmptyLinePrefix += "|";
+
+    makeRowSeparator(EmptyLinePrefix);
+    RST.insert(RST.begin() + Start, EmptyLinePrefix);
+    RST.insert(RST.end(), EmptyLinePrefix);
+  }
+
+  void VisitText(TextPiece *P) {
+    RST.push_back("");
+    auto &S = RST.back();
+
+    StringRef T = P->Text;
+    while (!T.empty() && T.front() == ' ') {
+      RST.back() += " |nbsp| ";
+      T = T.drop_front();
+    }
+
+    std::string Suffix;
+    while (!T.empty() && T.back() == ' ') {
+      Suffix += " |nbsp| ";
+      T = T.drop_back();
+    }
+
+    if (!T.empty()) {
+      S += ':';
+      S += P->Role;
+      S += ":`";
+      escapeRST(T, S);
+      S += '`';
+    }
+
+    S += Suffix;
+  }
+
+  void VisitPlaceholder(PlaceholderPiece *P) {
+    RST.push_back(std::string(":placeholder:`") +
+                  char('A' + mapIndex(P->Index)) + "`");
+  }
+
+  void VisitSelect(SelectPiece *P) {
+    std::vector<size_t> SeparatorIndexes;
+    SeparatorIndexes.push_back(RST.size());
+    RST.emplace_back();
+    for (auto *O : P->Options) {
+      Visit(O);
+      SeparatorIndexes.push_back(RST.size());
+      RST.emplace_back();
+    }
+
+    makeTableRows(RST.begin() + SeparatorIndexes.front(),
+                  RST.begin() + SeparatorIndexes.back() + 1);
+    for (size_t I : SeparatorIndexes)
+      makeRowSeparator(RST[I]);
+  }
+
+  void VisitDiff(DiffPiece *P) { Visit(P->Options[1]); }
+
+  std::vector<std::string> &RST;
+};
+
+struct DiagTextPrinter : DiagTextVisitor<DiagTextPrinter> {
+public:
+  using BaseTy = DiagTextVisitor<DiagTextPrinter>;
+  DiagTextPrinter(DiagnosticTextBuilder &Builder, std::string &Result)
+      : BaseTy(Builder), Result(Result) {}
+
+  void VisitMulti(MultiPiece *P) {
+    for (auto *Child : P->Pieces)
+      Visit(Child);
+  }
+  void VisitText(TextPiece *P) { Result += P->Text; }
+  void VisitPlaceholder(PlaceholderPiece *P) {
+    Result += "%";
+    Result += getModifierName(P->Kind);
+    addInt(mapIndex(P->Index));
+  }
+  void VisitSelect(SelectPiece *P) {
+    Result += "%";
+    Result += getModifierName(P->Kind);
+    if (P->Kind == MT_Select) {
+      Result += "{";
+      for (auto *D : P->Options) {
+        Visit(D);
+        Result += '|';
+      }
+      if (!P->Options.empty())
+        Result.erase(--Result.end());
+      Result += '}';
+    }
+    addInt(mapIndex(P->Index));
+  }
+
+  void VisitDiff(DiffPiece *P) {
+    Result += "%diff{";
+    Visit(P->Options[0]);
+    Result += "|";
+    Visit(P->Options[1]);
+    Result += "}";
+    addInt(mapIndex(P->Indexes[0]));
+    Result += ",";
+    addInt(mapIndex(P->Indexes[1]));
+  }
+
+  void addInt(unsigned Val) {
+    assert(Val < 10);
+    Result += static_cast<char>('0' + Val);
+  }
+
+  std::string &Result;
+};
+
+
+unsigned parseModifier(StringRef &Text) {
+  if (Text.empty() || !isdigit(Text[0]))
+    PrintFatalError("expected modifier in diagnostic");
+
+  unsigned Val = Text[0] - '0';
+  Text = Text.drop_front();
+  return Val;
+}
+
+Piece *DiagText::parseDiagText(StringRef &Text, bool Nested) {
+  std::vector<Piece *> Parsed;
+
+  while (!Text.empty()) {
+    size_t End = (size_t)-2;
+    do
+      End = Nested ? Text.find_first_of("%|}", End + 2)
+                   : Text.find_first_of('%', End + 2);
+    while (End < Text.size() - 1 && Text[End] == '%' &&
+           (Text[End + 1] == '%' || Text[End + 1] == '|'));
+
+    if (End) {
+      Parsed.push_back(create<TextPiece>(Text.slice(0, End), "diagtext"));
+      Text = Text.slice(End, StringRef::npos);
+      if (Text.empty())
+        break;
+    }
+
+    if (Text[0] == '|' || Text[0] == '}')
+      break;
+
+    // Drop the '%'.
+    Text = Text.drop_front();
+
+    // Extract the (optional) modifier.
+    size_t ModLength = Text.find_first_of("0123456789{");
+    StringRef Modifier = Text.slice(0, ModLength);
+    Text = Text.slice(ModLength, StringRef::npos);
+    ModifierType ModType = llvm::StringSwitch<ModifierType>{Modifier}
+                               .Case("select", MT_Select)
+                               .Case("sub", MT_Sub)
+                               .Case("diff", MT_Diff)
+                               .Case("plural", MT_Plural)
+                               .Case("s", MT_S)
+                               .Case("ordinal", MT_Ordinal)
+                               .Case("q", MT_Q)
+                               .Case("", MT_Placeholder)
+                               .Case("objcclass", MT_ObjCClass)
+                               .Case("objcinstance", MT_ObjCInstance)
+                               .Default(MT_Unknown);
+
+    switch (ModType) {
+    case MT_Unknown:
+      PrintFatalError("Unknown modifier type: " + Modifier);
+    case MT_Select:
+    case MT_Plural: {
+      SelectPiece *Select = create<SelectPiece>(ModType);
+      do {
+        Text = Text.drop_front();
+        if (ModType == MT_Plural)
+          while (Text[0] != ':')
+            Text = Text.drop_front();
+        Select->Options.push_back(parseDiagText(Text, true));
+        assert(!Text.empty() && "malformed %select");
+      } while (Text.front() == '|');
+      // Drop the trailing '}'.
+      Text = Text.drop_front(1);
+      Select->Index = parseModifier(Text);
+      Parsed.push_back(Select);
+      continue;
+    }
+    case MT_Sub: {
+      SubstitutionPiece *Sub = create<SubstitutionPiece>();
+      Text = Text.drop_front(); // '{'
+      size_t NameSize = Text.find_first_of('}');
+      assert(NameSize != size_t(-1) && "failed to find the end of the name");
+      assert(NameSize != 0 && "empty name?");
+      Sub->Name = Text.substr(0, NameSize).str();
+      Text = Text.drop_front(NameSize);
+      Text = Text.drop_front(); // '}'
+      if (!Text.empty()) {
+        while (true) {
+          if (!isdigit(Text[0]))
+            break;
+          Sub->Modifiers.push_back(parseModifier(Text));
+          if (Text.empty() || Text[0] != ',')
+            break;
+          Text = Text.drop_front(); // ','
+          assert(!Text.empty() && isdigit(Text[0]) &&
+                 "expected another modifier");
+        }
+      }
+      Parsed.push_back(Sub);
+      continue;
+    }
+    case MT_Diff: {
+      DiffPiece *Diff = create<DiffPiece>();
+      Text = Text.drop_front(); // '{'
+      Diff->Options[0] = parseDiagText(Text, true);
+      Text = Text.drop_front(); // '|'
+      Diff->Options[1] = parseDiagText(Text, true);
+
+      Text = Text.drop_front(); // '}'
+      Diff->Indexes[0] = parseModifier(Text);
+      Text = Text.drop_front(); // ','
+      Diff->Indexes[1] = parseModifier(Text);
+      Parsed.push_back(Diff);
+      continue;
+    }
+    case MT_S: {
+      SelectPiece *Select = create<SelectPiece>(ModType);
+      Select->Options.push_back(create<TextPiece>(""));
+      Select->Options.push_back(create<TextPiece>("s", "diagtext"));
+      Select->Index = parseModifier(Text);
+      Parsed.push_back(Select);
+      continue;
+    }
+    case MT_Q:
+    case MT_Placeholder:
+    case MT_ObjCClass:
+    case MT_ObjCInstance:
+    case MT_Ordinal: {
+      Parsed.push_back(create<PlaceholderPiece>(ModType, parseModifier(Text)));
+      continue;
+    }
+    }
+  }
+
+  return create<MultiPiece>(Parsed);
+}
+
+std::vector<std::string>
+DiagnosticTextBuilder::buildForDocumentation(StringRef Role, const Record *R) {
+  EvaluatingRecord = R;
+  std::string Text = R->getValueAsString("Text");
+  DiagText D(Role, Text);
+  std::vector<std::string> Result;
+  DiagTextDocPrinter{*this, Result}.Visit(D.Root);
+  return Result;
+}
+
+std::string DiagnosticTextBuilder::buildForDiagnostic(const Record *R) {
+  EvaluatingRecord = R;
+  std::string Text = R->getValueAsString("Text");
+  DiagText D(Text);
+  std::string Result;
+  DiagTextPrinter{*this, Result}.Visit(D.Root);
+  return Result;
+}
+
+} // namespace
+
 //===----------------------------------------------------------------------===//
 // Warning Tables (.inc file) generation.
 //===----------------------------------------------------------------------===//
 
 static bool isError(const Record &Diag) {
   const std::string &ClsName = Diag.getValueAsDef("Class")->getName();
   return ClsName == "CLASS_ERROR";
 }
 
 static bool isRemark(const Record &Diag) {
   const std::string &ClsName = Diag.getValueAsDef("Class")->getName();
   return ClsName == "CLASS_REMARK";
 }
 
+
 /// ClangDiagsDefsEmitter - The top-level class emits .def files containing
 /// declarations of Clang diagnostics.
 namespace clang {
 void EmitClangDiagsDefs(RecordKeeper &Records, raw_ostream &OS,
                         const std::string &Component) {
   // Write the #if guard
   if (!Component.empty()) {
     std::string ComponentName = StringRef(Component).upper();
     OS << "#ifdef " << ComponentName << "START\n";
     OS << "__" << ComponentName << "START = DIAG_START_" << ComponentName
        << ",\n";
     OS << "#undef " << ComponentName << "START\n";
     OS << "#endif\n\n";
   }
 
-  const std::vector<Record*> &Diags =
-    Records.getAllDerivedDefinitions("Diagnostic");
+  DiagnosticTextBuilder DiagTextBuilder(Records);
+
+  std::vector<Record *> Diags = Records.getAllDerivedDefinitions("Diagnostic");
 
   std::vector<Record*> DiagGroups
     = Records.getAllDerivedDefinitions("DiagGroup");
 
   std::map<std::string, GroupInfo> DiagsInGroup;
   groupDiagnostics(Diags, DiagGroups, DiagsInGroup);
 
   DiagCategoryIDMap CategoryIDs(Records);
   DiagGroupParentMap DGParentMap(Records);
 
   // Compute the set of diagnostics that are in -Wpedantic.
   RecordSet DiagsInPedantic;
   InferPedantic inferPedantic(DGParentMap, Diags, DiagGroups, DiagsInGroup);
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(R.getValueAsString("Text")) << '"';
+    OS.write_escaped(DiagTextBuilder.buildForDiagnostic(&R)) << '"';
 
     // Warning associated with the diagnostic. This is stored as an index into
     // the alphabetically sorted warning table.
     if (DefInit *DI = dyn_cast<DefInit>(R.getValueInit("Group"))) {
       std::map<std::string, GroupInfo>::iterator I =
           DiagsInGroup.find(DI->getDef()->getValueAsString("GroupName"));
       assert(I != DiagsInGroup.end());
       OS << ", " << I->second.IDNo;

 
 //===----------------------------------------------------------------------===//
 // Diagnostic documentation generation
 //===----------------------------------------------------------------------===//
 
 namespace docs {
 namespace {
 
-/// Diagnostic text, parsed into pieces.
-struct DiagText {
-  struct Piece {
-    // This type and its derived classes are move-only.
-    Piece() {}
-    Piece(Piece &&O) {}
-    Piece &operator=(Piece &&O) { return *this; }
-
-    virtual void print(std::vector<std::string> &RST) = 0;
-    virtual ~Piece() {}
-  };
-  struct TextPiece : Piece {
-    StringRef Role;
-    std::string Text;
-    void print(std::vector<std::string> &RST) override;
-  };
-  struct PlaceholderPiece : Piece {
-    int Index;
-    void print(std::vector<std::string> &RST) override;
-  };
-  struct SelectPiece : Piece {
-    SelectPiece() {}
-    SelectPiece(SelectPiece &&O) noexcept : Options(std::move(O.Options)) {}
-    std::vector<DiagText> Options;
-    void print(std::vector<std::string> &RST) override;
-  };
-
-  std::vector<std::unique_ptr<Piece>> Pieces;
-
-  DiagText();
-  DiagText(DiagText &&O) noexcept : Pieces(std::move(O.Pieces)) {}
-
-  DiagText(StringRef Text);
-  DiagText(StringRef Kind, StringRef Text);
-
-  template<typename P> void add(P Piece) {
-    Pieces.push_back(llvm::make_unique<P>(std::move(Piece)));
-  }
-  void print(std::vector<std::string> &RST);
-};
-
-DiagText parseDiagText(StringRef &Text, bool Nested = false) {
-  DiagText Parsed;
-
-  while (!Text.empty()) {
-    size_t End = (size_t)-2;
-    do
-      End = Nested ? Text.find_first_of("%|}", End + 2)
-                   : Text.find_first_of('%', End + 2);
-    while (End < Text.size() - 1 && Text[End] == '%' && Text[End + 1] == '%');
-
-    if (End) {
-      DiagText::TextPiece Piece;
-      Piece.Role = "diagtext";
-      Piece.Text = Text.slice(0, End);
-      Parsed.add(std::move(Piece));
-      Text = Text.slice(End, StringRef::npos);
-      if (Text.empty()) break;
-    }
-
-    if (Text[0] == '|' || Text[0] == '}')
-      break;
-
-    // Drop the '%'.
-    Text = Text.drop_front();
-
-    // Extract the (optional) modifier.
-    size_t ModLength = Text.find_first_of("0123456789{");
-    StringRef Modifier = Text.slice(0, ModLength);
-    Text = Text.slice(ModLength, StringRef::npos);
-
-    // FIXME: Handle %ordinal here.
-    if (Modifier == "select" || Modifier == "plural") {
-      DiagText::SelectPiece Select;
-      do {
-        Text = Text.drop_front();
-        if (Modifier == "plural")
-          while (Text[0] != ':')
-            Text = Text.drop_front();
-        Select.Options.push_back(parseDiagText(Text, true));
-        assert(!Text.empty() && "malformed %select");
-      } while (Text.front() == '|');
-      Parsed.add(std::move(Select));
-
-      // Drop the trailing '}n'.
-      Text = Text.drop_front(2);
-      continue;
-    }
-
-    // For %diff, just take the second alternative (tree diagnostic). It would
-    // be preferable to take the first one, and replace the $ with the suitable
-    // placeholders.
-    if (Modifier == "diff") {
-      Text = Text.drop_front(); // '{'
-      parseDiagText(Text, true);
-      Text = Text.drop_front(); // '|'
-
-      DiagText D = parseDiagText(Text, true);
-      for (auto &P : D.Pieces)
-        Parsed.Pieces.push_back(std::move(P));
-
-      Text = Text.drop_front(4); // '}n,m'
-      continue;
-    }
-
-    if (Modifier == "s") {
-      Text = Text.drop_front();
-      DiagText::SelectPiece Select;
-      Select.Options.push_back(DiagText(""));
-      Select.Options.push_back(DiagText("s"));
-      Parsed.add(std::move(Select));
-      continue;
-    }
-
-    assert(!Text.empty() && isdigit(Text[0]) && "malformed placeholder");
-    DiagText::PlaceholderPiece Placeholder;
-    Placeholder.Index = Text[0] - '0';
-    Parsed.add(std::move(Placeholder));
-    Text = Text.drop_front();
-    continue;
-  }
-  return Parsed;
-}
-
-DiagText::DiagText() {}
-
-DiagText::DiagText(StringRef Text) : DiagText(parseDiagText(Text, false)) {}
-
-DiagText::DiagText(StringRef Kind, StringRef Text) : DiagText(parseDiagText(Text, false)) {
-  TextPiece Prefix;
-  Prefix.Role = Kind;
-  Prefix.Text = Kind;
-  Prefix.Text += ": ";
-  Pieces.insert(Pieces.begin(),
-                llvm::make_unique<TextPiece>(std::move(Prefix)));
-}
-
-void escapeRST(StringRef Str, std::string &Out) {
-  for (auto K : Str) {
-    if (StringRef("`*|_[]\\").count(K))
-      Out.push_back('\\');
-    Out.push_back(K);
-  }
-}
-
-template<typename It> void padToSameLength(It Begin, It End) {
-  size_t Width = 0;
-  for (It I = Begin; I != End; ++I)
-    Width = std::max(Width, I->size());
-  for (It I = Begin; I != End; ++I)
-    (*I) += std::string(Width - I->size(), ' ');
-}
-
-template<typename It> void makeTableRows(It Begin, It End) {
-  if (Begin == End) return;
-  padToSameLength(Begin, End);
-  for (It I = Begin; I != End; ++I)
-    *I = "|" + *I + "|";
-}
-
-void makeRowSeparator(std::string &Str) {
-  for (char &K : Str)
-    K = (K == '|' ? '+' : '-');
-}
-
-void DiagText::print(std::vector<std::string> &RST) {
-  if (Pieces.empty()) {
-    RST.push_back("");
-    return;
-  }
-
-  if (Pieces.size() == 1)
-    return Pieces[0]->print(RST);
-
-  std::string EmptyLinePrefix;
-  size_t Start = RST.size();
-  bool HasMultipleLines = true;
-  for (auto &P : Pieces) {
-    std::vector<std::string> Lines;
-    P->print(Lines);
-    if (Lines.empty())
-      continue;
-
-    // We need a vertical separator if either this or the previous piece is a
-    // multi-line piece, or this is the last piece.
-    const char *Separator = (Lines.size() > 1 || HasMultipleLines) ? "|" : "";
-    HasMultipleLines = Lines.size() > 1;
-
-    if (Start + Lines.size() > RST.size())
-      RST.resize(Start + Lines.size(), EmptyLinePrefix);
-
-    padToSameLength(Lines.begin(), Lines.end());
-    for (size_t I = 0; I != Lines.size(); ++I)
-      RST[Start + I] += Separator + Lines[I];
-    std::string Empty(Lines[0].size(), ' ');
-    for (size_t I = Start + Lines.size(); I != RST.size(); ++I)
-      RST[I] += Separator + Empty;
-    EmptyLinePrefix += Separator + Empty;
-  }
-  for (size_t I = Start; I != RST.size(); ++I)
-    RST[I] += "|";
-  EmptyLinePrefix += "|";
-
-  makeRowSeparator(EmptyLinePrefix);
-  RST.insert(RST.begin() + Start, EmptyLinePrefix);
-  RST.insert(RST.end(), EmptyLinePrefix);
-}
-
-void DiagText::TextPiece::print(std::vector<std::string> &RST) {
-  RST.push_back("");
-  auto &S = RST.back();
-
-  StringRef T = Text;
-  while (!T.empty() && T.front() == ' ') {
-    RST.back() += " |nbsp| ";
-    T = T.drop_front();
-  }
-
-  std::string Suffix;
-  while (!T.empty() && T.back() == ' ') {
-    Suffix += " |nbsp| ";
-    T = T.drop_back();
-  }
-
-  if (!T.empty()) {
-    S += ':';
-    S += Role;
-    S += ":`";
-    escapeRST(T, S);
-    S += '`';
-  }
-  
-  S += Suffix;
-}
-
-void DiagText::PlaceholderPiece::print(std::vector<std::string> &RST) {
-  RST.push_back(std::string(":placeholder:`") + char('A' + Index) + "`");
-}
-
-void DiagText::SelectPiece::print(std::vector<std::string> &RST) {
-  std::vector<size_t> SeparatorIndexes;
-  SeparatorIndexes.push_back(RST.size());
-  RST.emplace_back();
-  for (auto &O : Options) {
-    O.print(RST);
-    SeparatorIndexes.push_back(RST.size());
-    RST.emplace_back();
-  }
-
-  makeTableRows(RST.begin() + SeparatorIndexes.front(),
-                RST.begin() + SeparatorIndexes.back() + 1);
-  for (size_t I : SeparatorIndexes)
-    makeRowSeparator(RST[I]);
-}
-
 bool isRemarkGroup(const Record *DiagGroup,
                    const std::map<std::string, GroupInfo> &DiagsInGroup) {
   bool AnyRemarks = false, AnyNonRemarks = false;
 
   std::function<void(StringRef)> Visit = [&](StringRef GroupName) {
     auto &GroupInfo = DiagsInGroup.find(GroupName)->second;
     for (const Record *Diag : GroupInfo.DiagsInGroup)
       (isRemark(*Diag) ? AnyRemarks : AnyNonRemarks) = true;
getDefaultSeverities(const Record *DiagGroup,
   Visit(DiagGroup->getValueAsString("GroupName"));
   return States;
 }
 
 void writeHeader(StringRef Str, raw_ostream &OS, char Kind = '-') {
   OS << Str << "\n" << std::string(Str.size(), Kind) << "\n";
 }
 
-void writeDiagnosticText(StringRef Role, StringRef Text, raw_ostream &OS) {
+void writeDiagnosticText(DiagnosticTextBuilder &Builder, const Record *R,
+                         StringRef Role, raw_ostream &OS) {
+  StringRef Text = R->getValueAsString("Text");
   if (Text == "%0")
     OS << "The text of this diagnostic is not controlled by Clang.\n\n";
   else {
-    std::vector<std::string> Out;
-    DiagText(Role, Text).print(Out);
+    std::vector<std::string> Out = Builder.buildForDocumentation(Role, R);
     for (auto &Line : Out)
       OS << Line << "\n";
     OS << "\n";
   }
 }
 
 }  // namespace
 }  // namespace docs
 
 void EmitClangDiagDocs(RecordKeeper &Records, raw_ostream &OS) {
   using namespace docs;
 
   // Get the documentation introduction paragraph.
   const Record *Documentation = Records.getDef("GlobalDocumentation");
   if (!Documentation) {
     PrintFatalError("The Documentation top-level definition is missing, "
                     "no documentation will be generated.");
     return;
   }
 
   OS << Documentation->getValueAsString("Intro") << "\n";
 
+  DiagnosticTextBuilder Builder(Records);
+
   std::vector<Record*> Diags =
       Records.getAllDerivedDefinitions("Diagnostic");
+
   std::vector<Record*> DiagGroups =
       Records.getAllDerivedDefinitions("DiagGroup");
   llvm::sort(DiagGroups.begin(), DiagGroups.end(), diagGroupBeforeByName);
 
   DiagGroupParentMap DGParentMap(Records);
 
   std::map<std::string, GroupInfo> DiagsInGroup;
   groupDiagnostics(Diags, DiagGroups, DiagsInGroup);
for (const Record *G : DiagGroups) {
 
     if (!GroupInfo.DiagsInGroup.empty()) {
       OS << "**Diagnostic text:**\n\n";
       for (const Record *D : GroupInfo.DiagsInGroup) {
         auto Severity = getDefaultSeverity(D);
         Severity[0] = tolower(Severity[0]);
         if (Severity == "ignored")
           Severity = IsRemarkGroup ? "remark" : "warning";
-        writeDiagnosticText(Severity, D->getValueAsString("Text"), OS);
+
+        writeDiagnosticText(Builder, D, Severity, OS);
       }
     }
 
     auto Doc = G->getValueAsString("Documentation");
     if (!Doc.empty())
       OS << Doc;
     else if (GroupInfo.SubGroups.empty() && GroupInfo.DiagsInGroup.empty())
       OS << "This diagnostic flag exists for GCC compatibility, and has no "
             "effect in Clang.\n";
     OS << "\n";
   }
 }
 
 } // end namespace clang