Update docstrings and comments

Work on mypyc/mypyc#714.
python · JukkaL · Feb 22, 2020 · Feb 22, 2020 · Feb 22, 2020 · Feb 22, 2020
commit 23a7c83975f547b408ef571fb7ba7947f881b5a5
diff --git a/mypyc/genops.py b/mypyc/genops.py
@@ -1,19 +1,14 @@
-"""Transform a mypy AST to the IR form (Intermediate Representation).
+"""Builder class used to transform a mypy AST to the IR form.
 
-For example, consider a function like this:
+The IRBuilder class maintains transformation state and provides access
+to various helpers used to implement the transform.
 
-   def f(x: int) -> int:
-       return x * 2 + 1
+The top-level transform control logic is in mypyc.genopsmain.
 
-It would be translated to something that conceptually looks like this:
-
-   r0 = 2
-   r1 = 1
-   r2 = x * r0 :: int
-   r3 = r2 + r1 :: int
-   return r3
-
-The IR is implemented in mypyc.ops.
+mypyc.genopsvisitor.IRBuilderVisitor is used to dispatch based on mypy
+AST node type to code that actually does the bulk of the work. For
+example, expressions are transformed in mypyc.genexpr and functions are
+transformed in mypyc.genfunc.
 """
 
 from typing import Callable, Dict, List, Tuple, Optional, Union, Sequence, Set, Any

diff --git a/mypyc/genopsmain.py b/mypyc/genopsmain.py
@@ -1,3 +1,24 @@
+"""Transform a mypy AST to the IR form (Intermediate Representation).
+
+For example, consider a function like this:
+
+   def f(x: int) -> int:
+       return x * 2 + 1
+
+It would be translated to something that conceptually looks like this:
+
+   r0 = 2
+   r1 = 1
+   r2 = x * r0 :: int
+   r3 = r2 + r1 :: int
+   return r3
+
+The IR is implemented in mypyc.ops.
+
+For the core of the implementation, look at build_ir() below,
+mypyc.genops, and mypyc.genopsvisitor.
+"""
+
 from collections import OrderedDict
 from typing import List, Dict, Callable, Any, TypeVar, cast
 

diff --git a/mypyc/genopsvisitor.py b/mypyc/genopsvisitor.py
@@ -1,3 +1,8 @@
+"""Dispatcher used when transforming a mypy AST to the IR form.
+
+mypyc.genops and mypyc.genopsmain are closely related.
+"""
+
 from typing_extensions import NoReturn
 
 from mypy.nodes import (
@@ -23,6 +28,20 @@
 
 
 class IRBuilderVisitor(IRVisitor):
+    """Mypy node visitor that dispatches to node transform implementations.
+
+    This class should have no non-trivial logic.
+
+    This visitor is separated from the rest of code to improve modularity and
+    to avoid import cycles.
+
+    This is based on the visitor pattern
+    (https://en.wikipedia.org/wiki/Visitor_pattern).
+    """
+
+    # This gets passed to all the implementations and contains all the
+    # state and many helpers. The attribute is initialized outside
+    # this class since this class and IRBuilder form a reference loop.
     builder = None  # type: IRBuilder
 
     def visit_mypy_file(self, mypyfile: MypyFile) -> None:
@@ -194,10 +213,12 @@ def visit_await_expr(self, o: AwaitExpr) -> Value:
         return BuildFuncIR(self.builder).visit_await_expr(o)
 
     # Unimplemented constructs
+
     def visit_assignment_expr(self, o: AssignmentExpr) -> Value:
         self.bail("I Am The Walrus (unimplemented)", o.line)
 
     # Unimplemented constructs that shouldn't come up because they are py2 only
+
     def visit_backquote_expr(self, o: BackquoteExpr) -> Value:
         self.bail("Python 2 features are unsupported", o.line)
 
@@ -211,6 +232,7 @@ def visit_unicode_expr(self, o: UnicodeExpr) -> Value:
         self.bail("Python 2 features are unsupported", o.line)
 
     # Constructs that shouldn't ever show up
+
     def visit_enum_call_expr(self, o: EnumCallExpr) -> Value:
         assert False, "can't compile analysis-only expressions"
 
@@ -250,6 +272,8 @@ def visit_cast_expr(self, o: CastExpr) -> Value:
     def visit_star_expr(self, o: StarExpr) -> Value:
         assert False, "should have been handled in Tuple/List/Set/DictExpr or CallExpr"
 
+    # Helpers
+
     def bail(self, msg: str, line: int) -> NoReturn:
         """Reports an error and aborts compilation up until the last accept() call