[clang] 984cf99 - [clang][NFC] Add some documentation about the use of NamedDecl::getDeclName in diagnostics.

[Bruno Ricci via cfe-commits]

Author: Bruno Ricci
Date: 2020-07-28T15:39:17+01:00
New Revision: 984cf99055a292b3afe4535c013d38914a3da880

URL: https://github.com/llvm/llvm-project/commit/984cf99055a292b3afe4535c013d38914a3da880
DIFF: https://github.com/llvm/llvm-project/commit/984cf99055a292b3afe4535c013d38914a3da880.diff

LOG: [clang][NFC] Add some documentation about the use of NamedDecl::getDeclName in diagnostics.

As explained in eb10b065f2a870b425dcc2040b9955e0eee464b4, sending a NamedDecl*
in a diagnostic should generally be preferred over sending the DeclarationName
from getDeclName(). Let's document that.

Added: 
    

Modified: 
    clang/include/clang/AST/Decl.h

Removed: 
    


################################################################################
diff  --git a/clang/include/clang/AST/Decl.h b/clang/include/clang/AST/Decl.h
index 28faa2c1fc78..4dd5e14d36e1 100644
--- a/clang/include/clang/AST/Decl.h
+++ b/clang/include/clang/AST/Decl.h
@@ -269,6 +269,19 @@ class NamedDecl : public Decl {
 
   /// Get the actual, stored name of the declaration, which may be a special
   /// name.
+  ///
+  /// Note that generally in diagnostics, the non-null \p NamedDecl* itself
+  /// should be sent into the diagnostic instead of using the result of
+  /// \p getDeclName().
+  ///
+  /// A \p DeclarationName in a diagnostic will just be streamed to the output,
+  /// which will directly result in a call to \p DeclarationName::print.
+  ///
+  /// A \p NamedDecl* in a diagnostic will also ultimately result in a call to
+  /// \p DeclarationName::print, but with two customisation points along the
+  /// way (\p getNameForDiagnostic and \p printName). These are used to print
+  /// the template arguments if any, and to provide a user-friendly name for
+  /// some entities (such as unnamed variables and anonymous records).
   DeclarationName getDeclName() const { return Name; }
 
   /// Set the name of this declaration.