From 76eec230b435ab1e2784a8746008a9516648f02b Mon Sep 17 00:00:00 2001
From: Jukka Lehtosalo <jukka.lehtosalo@iki.fi>
Date: Mon, 9 Oct 2017 13:21:42 +0100
Subject: [PATCH 1/2] Update documentation of SymbolTableNode

---
 mypy/nodes.py | 46 +++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 41 insertions(+), 5 deletions(-)

diff --git a/mypy/nodes.py b/mypy/nodes.py
index 1545e469a12e..aa47f68851ea 100644
--- a/mypy/nodes.py
+++ b/mypy/nodes.py
@@ -2234,21 +2234,55 @@ 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]
     # Module id (e.g. "foo.bar") or None
     mod_id = ''  # type: Optional[str]
-    # 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.)
@@ -2262,6 +2296,8 @@ class SymbolTableNode:
     # 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?
+    #
+    # TODO: Write a better comment, this is confusing
     normalized = False  # type: bool
     # Was this defined by assignment to self attribute?
     implicit = False  # type: bool

From 0475332140f92e824d3d1e4d9b2ef9d25c9d860c Mon Sep 17 00:00:00 2001
From: Jukka Lehtosalo <jukka.lehtosalo@iki.fi>
Date: Mon, 9 Oct 2017 15:43:02 +0100
Subject: [PATCH 2/2] Update comment of normalized

---
 mypy/nodes.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/mypy/nodes.py b/mypy/nodes.py
index aa47f68851ea..a0dcfe4aa038 100644
--- a/mypy/nodes.py
+++ b/mypy/nodes.py
@@ -2295,9 +2295,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?
-    #
-    # TODO: Write a better comment, this is confusing
+    # 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