improve doc & naming

JelleZijlstra · Jun 17, 2024 · Jun 3, 2024 · Jun 3, 2024 · Jun 3, 2024 · Jun 3, 2024
commit 74d330ed03c1ba937f7eb97a7d22d9a143b38c63
diff --git a/Include/internal/pycore_symtable.h b/Include/internal/pycore_symtable.h
@@ -29,26 +29,29 @@ typedef enum _comprehension_type {
     SetComprehension = 3,
     GeneratorExpression = 4 } _Py_comprehension_ty;
 
-/* Additional flags that are set temporarily on a symtable object.
+/* Additional flags that are set temporarily on a ``_symtable_entry`` object.
  *
  * Those flags are only used to add some information on the current context.
  */
-typedef enum _extra_flags {
+typedef enum _extra_flags_e {
     // Mutually exclusive flags indicating the kind of type variable
-    // being processed.
+    // being processed. Use this flag to avoid passing or checking
+    // twice the kind of a ``type_param_ty`` object.
     InTypeVar = 1,
     InTypeVarTuple = 2,
     InParamSpec = (1 << 2),
 
     // Mutually exclusive flags indicating which component of
-    // a type parameters block (PEP 695) is being processed.
+    // a type parameters block is being processed. Those flags
+    // are used in conjunction with 'InTypeVar', 'InTypeVarTuple'
+    // or 'InParamSpec' but not all combinations are supported.
     InTypeParamBound = (1 << 3),
     InTypeParamConstraint = (1 << 4),
     InTypeParamDefault = (1 << 5),
-} _Py_extra_fls;
+} _extra_flags_t;
 
 #define CLEAR_TYPE_PARAM_KIND_EXTRA_FLAGS ~(InTypeVar | InTypeVarTuple | InParamSpec)
-#define CLEAR_TYPE_PARAM_EXTRA_FLAGS ~(InTypeParamBound | InTypeParamConstraint | InTypeParamDefault)
+#define CLEAR_TYPE_PARAM_ATTR_EXTRA_FLAGS ~(InTypeParamBound | InTypeParamConstraint | InTypeParamDefault)
 
 /* source location information */
 typedef struct {
@@ -104,7 +107,7 @@ typedef struct _symtable_entry {
     PyObject *ste_directives;/* locations of global and nonlocal statements */
     PyObject *ste_mangled_names; /* set of names for which mangling should be applied */
     _Py_block_ty ste_type;
-    _Py_extra_fls ste_extra_flags;
+    _extra_flags_t ste_extra_flags; /* extra temporary flags */
     int ste_nested;      /* true if block is nested */
     unsigned ste_free : 1;        /* true if block has free variables */
     unsigned ste_child_free : 1;  /* true if a child block has free vars,

@@ -2301,7 +2301,7 @@ symtable_visit_type_param_bound_or_default(struct symtable *st, expr_ty e, ident
         if (!symtable_enter_block(st, name, TypeVarBoundBlock, key, LOCATION(e)))
             return 0;
 
-        st->st_cur->ste_extra_flags &= CLEAR_TYPE_PARAM_EXTRA_FLAGS;
+        st->st_cur->ste_extra_flags &= CLEAR_TYPE_PARAM_ATTR_EXTRA_FLAGS;
         st->st_cur->ste_extra_flags |= (is_default == 1 ? InTypeParamDefault : (
             e->kind == Tuple_kind ? InTypeParamConstraint : InTypeParamBound
         ));
@@ -2753,7 +2753,7 @@ symtable_raise_if_annotation_block(struct symtable *st, const char *name, expr_t
     if (type == AnnotationBlock)
         PyErr_Format(PyExc_SyntaxError, ANNOTATION_NOT_ALLOWED, name);
     else if (type == TypeVarBoundBlock) {
-        enum _extra_flags flags = st->st_cur->ste_extra_flags;
+        _extra_flags_t flags = st->st_cur->ste_extra_flags;
         PyErr_Format(
             PyExc_SyntaxError, EXPR_NOT_ALLOWED_IN_TYPE_PARAM_BLOCK, name, (
                 (flags & InTypeVar) ? "a TypeVar" :