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

[ericsnowcurrently]

https://github.com/python/cpython/commit/21412d037b07c08266e96dfd0c0e44a1b7693bc1
commit: 21412d037b07c08266e96dfd0c0e44a1b7693bc1
branch: main
author: Eric Snow <ericsnowcurrently at gmail.com>
committer: ericsnowcurrently <ericsnowcurrently at gmail.com>
date: 2022-03-23T09:52:50-06:00
summary:

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

files:
M Include/internal/pycore_global_strings.h

diff --git a/Include/internal/pycore_global_strings.h b/Include/internal/pycore_global_strings.h
index 1d83bf2cfad4c..3e533fd16509f 100644
--- 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