python
diff --git a/‎mypy/nodes.py
Lines changed: 42 additions & 6 deletions b/‎mypy/nodes.py
Lines changed: 42 additions & 6 deletions
@@ -2233,19 +2233,53 @@ def __getattribute__(self, attr: str) -> None:
 
 
 class SymbolTableNode:
+    """Description of a name binding in a symbol table.
+
+    These are only used as values in module (global), function (local)
+    and class symbol tables (see SymbolTable). The name that is bound is
+    the key in SymbolTable.
+
+    Symbol tables don't contain direct references to AST nodes primarily
+    because there can be multiple symbol table references to a single
+    AST node (due to imports and aliases), and different references can
+    behave differently. This class describes the unique properties of
+    each reference.
+
+    The most fundamental attributes are 'kind' and 'node'.  The 'node'
+    attribute defines the AST node that the name refers to.
+
+    For many bindings, including those targeting variables, functions
+    and classes, the kind is one of LDEF, GDEF or MDEF, depending on the
+    scope of the definition. These three kinds can usually be used
+    interchangeably and the difference between local, global and class
+    scopes is mostly descriptive, with no semantic significance.
+    However, some tools that consume mypy ASTs may care about these so
+    they should be correct.
+
+    A few definitions get special kinds, including type variables (TVAR),
+    imported modules and module aliases (MODULE_REF), and type aliases
+    (TYPE_ALIAS).
+
+    Type aliases are very special and have additional attributes that
+    are only used for them ('type_override', 'alias_tvars' at least).
+    """
+    # TODO: This is a mess. Refactor!
+    # TODO: Describe how type aliases work.
+
     # Kind of node. Possible values:
-    #  - LDEF: local definition (of any kind)
+    #  - LDEF: local definition
     #  - GDEF: global (module-level) definition
     #  - MDEF: class member definition
-    #  - TVAR: TypeVar(...) definition
+    #  - TVAR: TypeVar(...) definition in any scope
     #  - MODULE_REF: reference to a module
     #  - TYPE_ALIAS: type alias
-    #  - UNBOUND_IMPORTED: temporary kind for imported names
+    #  - UNBOUND_IMPORTED: temporary kind for imported names (we don't know the final kind yet)
     kind = None  # type: int
-    # AST node of definition (FuncDef/Var/TypeInfo/Decorator/TypeVarExpr,
+    # AST node of definition (among others, this can be FuncDef/Var/TypeInfo/TypeVarExpr/MypyFile,
     # or None for a bound type variable).
     node = None  # type: Optional[SymbolNode]
-    # If this not None, override the type of the 'node' attribute.
+    # If this not None, override the type of the 'node' attribute. This is only used for
+    # type aliases.
     type_override = None  # type: Optional[mypy.types.Type]
     # For generic aliases this stores the (qualified) names of type variables.
     # (For example see testGenericAliasWithTypeVarsFromDifferentModules.)
@@ -2258,7 +2292,9 @@ class SymbolTableNode:
     # For deserialized MODULE_REF nodes, the referenced module name;
     # for other nodes, optionally the name of the referenced object.
     cross_ref = None  # type: Optional[str]
-    # Was this node created by normalіze_type_alias?
+    # Used to distinguish between 'typing.List' and 'builtins.list'.  This is
+    # True when the former has been normalized to the latter, and it allow us
+    # to reject 'list[str]' and similar.
     normalized = False  # type: bool
     # Was this defined by assignment to self attribute?
     implicit = False  # type: bool