[mypyc] Improve docstrings and comments in mypyc.ir (#8514)

Added lots of docstrings and comments, and also added detail to existing
documentation.

Also did some minor refactoring (just moving things around).

Author: JukkaL

mypyc/ir/class_ir.py

@@ -86,47 +86,12 @@
 VTableEntries = List[VTableEntry]
 
 
-def serialize_vtable_entry(entry: VTableEntry) -> JsonDict:
-    if isinstance(entry, VTableMethod):
-        return {
-            '.class': 'VTableMethod',
-            'cls': entry.cls.fullname,
-            'name': entry.name,
-            'method': entry.method.decl.fullname,
-            'shadow_method': entry.shadow_method.decl.fullname if entry.shadow_method else None,
-        }
-    else:
-        return {
-            '.class': 'VTableAttr',
-            'cls': entry.cls.fullname,
-            'name': entry.name,
-            'is_setter': entry.is_setter,
-        }
-
-
-def serialize_vtable(vtable: VTableEntries) -> List[JsonDict]:
-    return [serialize_vtable_entry(v) for v in vtable]
-
-
-def deserialize_vtable_entry(data: JsonDict, ctx: 'DeserMaps') -> VTableEntry:
-    if data['.class'] == 'VTableMethod':
-        return VTableMethod(
-            ctx.classes[data['cls']], data['name'], ctx.functions[data['method']],
-            ctx.functions[data['shadow_method']] if data['shadow_method'] else None)
-    elif data['.class'] == 'VTableAttr':
-        return VTableAttr(ctx.classes[data['cls']], data['name'], data['is_setter'])
-    assert False, "Bogus vtable .class: %s" % data['.class']
-
-
-def deserialize_vtable(data: List[JsonDict], ctx: 'DeserMaps') -> VTableEntries:
-    return [deserialize_vtable_entry(x, ctx) for x in data]
-
-
 class ClassIR:
     """Intermediate representation of a class.
 
     This also describes the runtime structure of native instances.
     """
+
     def __init__(self, name: str, module_name: str, is_trait: bool = False,
                  is_generated: bool = False, is_abstract: bool = False,
                  is_ext_class: bool = True) -> None:
@@ -139,15 +104,17 @@ def __init__(self, name: str, module_name: str, is_trait: bool = False,
         # An augmented class has additional methods separate from what mypyc generates.
         # Right now the only one is dataclasses.
         self.is_augmented = False
+        # Does this inherit from a Python class?
         self.inherits_python = False
+        # Do instances of this class have __dict__?
         self.has_dict = False
         # Do we allow interpreted subclasses? Derived from a mypyc_attr.
         self.allow_interpreted_subclasses = False
         # If this a subclass of some built-in python class, the name
         # of the object for that class. We currently only support this
         # in a few ad-hoc cases.
         self.builtin_base = None  # type: Optional[str]
-        # Default empty ctor
+        # Default empty constructor
         self.ctor = FuncDecl(name, None, module_name, FuncSignature([], RInstance(self)))
 
         self.attributes = OrderedDict()  # type: OrderedDict[str, RType]
@@ -398,8 +365,7 @@ def deserialize(cls, data: JsonDict, ctx: 'DeserMaps') -> 'ClassIR':
 
 
 class NonExtClassInfo:
-    """Information needed to construct a non-extension class.
-
+    """Information needed to construct a non-extension class (Python class).
 
     Includes the class dictionary, a tuple of base classes,
     the class annotations dictionary, and the metaclass.
@@ -412,6 +378,42 @@ def __init__(self, dict: Value, bases: Value, anns: Value, metaclass: Value) ->
         self.metaclass = metaclass
 
 
+def serialize_vtable_entry(entry: VTableEntry) -> JsonDict:
+    if isinstance(entry, VTableMethod):
+        return {
+            '.class': 'VTableMethod',
+            'cls': entry.cls.fullname,
+            'name': entry.name,
+            'method': entry.method.decl.fullname,
+            'shadow_method': entry.shadow_method.decl.fullname if entry.shadow_method else None,
+        }
+    else:
+        return {
+            '.class': 'VTableAttr',
+            'cls': entry.cls.fullname,
+            'name': entry.name,
+            'is_setter': entry.is_setter,
+        }
+
+
+def serialize_vtable(vtable: VTableEntries) -> List[JsonDict]:
+    return [serialize_vtable_entry(v) for v in vtable]
+
+
+def deserialize_vtable_entry(data: JsonDict, ctx: 'DeserMaps') -> VTableEntry:
+    if data['.class'] == 'VTableMethod':
+        return VTableMethod(
+            ctx.classes[data['cls']], data['name'], ctx.functions[data['method']],
+            ctx.functions[data['shadow_method']] if data['shadow_method'] else None)
+    elif data['.class'] == 'VTableAttr':
+        return VTableAttr(ctx.classes[data['cls']], data['name'], data['is_setter'])
+    assert False, "Bogus vtable .class: %s" % data['.class']
+
+
+def deserialize_vtable(data: List[JsonDict], ctx: 'DeserMaps') -> VTableEntries:
+    return [deserialize_vtable_entry(x, ctx) for x in data]
+
+
 def all_concrete_classes(class_ir: ClassIR) -> Optional[List[ClassIR]]:
     """Return all concrete classes among the class itself and its subclasses."""
     concrete = class_ir.concrete_subclasses()

mypyc/ir/func_ir.py

@@ -1,3 +1,5 @@
+"""Intermediate representation of functions."""
+
 from typing import List, Optional, Sequence, Dict
 from typing_extensions import Final
 
@@ -12,6 +14,11 @@
 
 
 class RuntimeArg:
+    """Representation of a function argument in IR.
+
+    Argument kind is one of ARG_* constants defined in mypy.nodes.
+    """
+
     def __init__(self, name: str, typ: RType, kind: int = ARG_POS) -> None:
         self.name = name
         self.type = typ
@@ -37,7 +44,10 @@ def deserialize(cls, data: JsonDict, ctx: DeserMaps) -> 'RuntimeArg':
 
 
 class FuncSignature:
-    # TODO: track if method?
+    """Signature of a function in IR."""
+
+    # TODO: Track if method?
+
     def __init__(self, args: Sequence[RuntimeArg], ret_type: RType) -> None:
         self.args = tuple(args)
         self.ret_type = ret_type
@@ -62,6 +72,12 @@ def deserialize(cls, data: JsonDict, ctx: DeserMaps) -> 'FuncSignature':
 
 
 class FuncDecl:
+    """Declaration of a function in IR (without body or implementation).
+
+    A function can be a regular module-level function, a method, a
+    static method, a class method, or a property getter/setter.
+    """
+
     def __init__(self,
                  name: str,
                  class_name: Optional[str],
@@ -129,7 +145,11 @@ def deserialize(cls, data: JsonDict, ctx: DeserMaps) -> 'FuncDecl':
 
 
 class FuncIR:
-    """Intermediate representation of a function with contextual information."""
+    """Intermediate representation of a function with contextual information.
+
+    Unlike FuncDecl, this includes the IR of the body (basic blocks) and an
+    environment.
+    """
 
     def __init__(self,
                  decl: FuncDecl,
@@ -199,6 +219,7 @@ def deserialize(cls, data: JsonDict, ctx: DeserMaps) -> 'FuncIR':
 
 
 def format_blocks(blocks: List[BasicBlock], env: Environment) -> List[str]:
+    """Format a list of IR basic blocks into a human-readable form."""
     # First label all of the blocks
     for i, block in enumerate(blocks):
         block.label = i