bpo-46541: Add a Comment About When to Use _Py_DECLARE_STR(). (gh-32063)

In a gh-32003 comment, I realized it wasn't very clear how _Py_DECLARE_STR() should be used.  This changes adds a comment to clarify.

https://bugs.python.org/issue46541

diff --git a/Include/internal/pycore_global_strings.h b/Include/internal/pycore_global_strings.h
index 1d83bf2cfad4c729b1974318a2eb40c50cdb4c21..3e533fd16509f3d3678806971899ad221b0398eb 100644 (file)
--- a/Include/internal/pycore_global_strings.h
+++ b/Include/internal/pycore_global_strings.h
@@ -372,6 +372,16 @@ struct _Py_global_strings {
 #define _Py_STR(NAME) \
      (_Py_SINGLETON(strings.literals._ ## NAME._ascii.ob_base))
 
+/* _Py_DECLARE_STR() should precede all uses of _Py_STR() in a function.
+
+   This is true even if the same string has already been declared
+   elsewhere, even in the same file.  Mismatched duplicates are detected
+   by Tools/scripts/generate-global-objects.py.
+
+   Pairing _Py_DECLARE_STR() with every use of _Py_STR() makes sure the
+   string keeps working even if the declaration is removed somewhere
+   else.  It also makes it clear what the actual string is at every
+   place it is being used. */
 #define _Py_DECLARE_STR(name, str)
 
 #ifdef __cplusplus