diff --git a/clang/docs/InternalsManual.html b/clang/docs/InternalsManual.html index cca9960d835b..77b75bbd188e 100644 --- a/clang/docs/InternalsManual.html +++ b/clang/docs/InternalsManual.html @@ -327,13 +327,19 @@ href="#SourceLocation">SourceLocation object) and a diagnostic enum value (which matches the name from DiagnosticKinds.def). If the diagnostic takes arguments, they are specified with the << operator: the first argument becomes %0, the second becomes %1, etc. The diagnostic interface allows you to -specify arguments -SourceRanges are also specified with -the << operator, and do not have a specific ordering.
+specify arguments of many different types, including int and +unsigned for integer arguments, const char* and +std::string for string arguments, DeclarationName and +const IdentifierInfo* for names, QualType for types, etc. +SourceRanges are also specified with the << operator, but do not have a +specific ordering requirement.As you can see, adding and producing a diagnostic is pretty straightforward. The hard part is deciding exactly what you need to say to help the user, picking a suitable wording, and providing the information needed to format it correctly. +The good news is that the call site that issues a diagnostic should be +completely independent of how the diagnostic is formatted and in what language +it is rendered.
@@ -356,17 +362,27 @@ code, the source ranges, and the caret. However, this behavior isn't required.Another implementation of the DiagnosticClient interface is the 'TextDiagnosticBuffer' class, which is used when clang is in -verify mode. -Instead of formatting and printing out the diagnostics, this implementation +Instead of formatting and printing out the diagnostics, this implementation just +captures and remembers the diagnostics as they fly by. Then -verify compares +the list of produced diagnostics to the list of expected ones. If they diagree, +it prints out its own output.
-Clang command line, buffering, HTMLizing, etc.
+There are many other possible implementations of this interface, and this is +why we prefer diagnostics to pass down rich structured information in arguments. +For example, an HTML output might want declaration names be linkified to where +they come from in the source. Another example is that a GUI might let you click +on typedefs to expand them. This application would want to pass significantly +more information about types through to the GUI than a simple flat string. The +interface allows this to happen.
Not possible yet! Diagnostic strings should be written in UTF-8, the client -can translate to the relevant code page if needed.
+can translate to the relevant code page if needed. Each translation completely +replaces the format string for the diagnostic.