Add comments to the diagnostic kinds in Diagnostic.td.

[thakis]

Not sure if this is useful, but this is where I always check first.

[hans]

Highly useful I'd say!

lgtm

include/clang/Basic/Diagnostic.td

113

Nit: On first glance, one might parse this as the accepted language extensions being enabled by -pedantic, not the warnings. Maybe spell it out: "about accepted language extensions. The warnings are default-off bug enabled by -pedantic."

[thakis]

r301039, thanks.

[• mdxmoe]

This comment was removed by chandlerc.

[• ytiw92]

This comment was removed by chandlerc.

[• Johnniesnato]

This comment was removed by chandlerc.

include/clang/Basic/Diagnostic.td

 //===--- 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">;

 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 that are
+// default-off but enabled by -pedantic.
 class Extension<string str> : Diagnostic<str, CLASS_EXTENSION, SEV_Ignored>;
+// ExtWarns are warnings about accepted language extensions that 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 {