[clang] 7d9f913 - Update comment on getCustomDiagID; NFC

[Aaron Ballman via cfe-commits]

Author: Aaron Ballman
Date: 2025-07-22T07:27:00-04:00
New Revision: 7d9f913bb4164b8aaecfc17accebd44044592115

URL: https://github.com/llvm/llvm-project/commit/7d9f913bb4164b8aaecfc17accebd44044592115
DIFF: https://github.com/llvm/llvm-project/commit/7d9f913bb4164b8aaecfc17accebd44044592115.diff

LOG: Update comment on getCustomDiagID; NFC

These APIs should almost never be used in Clang, so documenting that
more clearly. The problem is that the diagnostics are never associated
with a diagnostic group, so users have no way to control warning
behavior associated with the diagnostic. That makes for a poor user
experience. Instead, use a real diagnostic whenever possible or the API
taking a CustomDiagDesc as a last resort.

Added: 
    

Modified: 
    clang/include/clang/Basic/Diagnostic.h
    clang/include/clang/Basic/DiagnosticIDs.h

Removed: 
    


################################################################################
diff  --git a/clang/include/clang/Basic/Diagnostic.h b/clang/include/clang/Basic/Diagnostic.h
index c7a627600f3cc..cee5bed665d0a 100644
--- a/clang/include/clang/Basic/Diagnostic.h
+++ b/clang/include/clang/Basic/Diagnostic.h
@@ -895,7 +895,10 @@ class DiagnosticsEngine : public RefCountedBase<DiagnosticsEngine> {
   /// \param FormatString A fixed diagnostic format string that will be hashed
   /// and mapped to a unique DiagID.
   template <unsigned N>
-  // TODO: Deprecate this once all uses are removed from Clang.
+  // FIXME: this API should almost never be used; custom diagnostics do not
+  // have an associated diagnostic group and thus cannot be controlled by users
+  // like other diagnostics. The number of times this API is used in Clang
+  // should only ever be reduced, not increased.
   // [[deprecated("Use a CustomDiagDesc instead of a Level")]]
   unsigned getCustomDiagID(Level L, const char (&FormatString)[N]) {
     return Diags->getCustomDiagID((DiagnosticIDs::Level)L,

diff  --git a/clang/include/clang/Basic/DiagnosticIDs.h b/clang/include/clang/Basic/DiagnosticIDs.h
index 2b095f0fd6741..f07a003f3fdef 100644
--- a/clang/include/clang/Basic/DiagnosticIDs.h
+++ b/clang/include/clang/Basic/DiagnosticIDs.h
@@ -283,7 +283,10 @@ class DiagnosticIDs : public RefCountedBase<DiagnosticIDs> {
   // writing, nearly all callers of this function were invalid.
   unsigned getCustomDiagID(CustomDiagDesc Diag);
 
-  // TODO: Deprecate this once all uses are removed from LLVM
+  // FIXME: this API should almost never be used; custom diagnostics do not
+  // have an associated diagnostic group and thus cannot be controlled by users
+  // like other diagnostics. The number of times this API is used in Clang
+  // should only ever be reduced, not increased.
   // [[deprecated("Use a CustomDiagDesc instead of a Level")]]
   unsigned getCustomDiagID(Level Level, StringRef Message) {
     return getCustomDiagID([&]() -> CustomDiagDesc {