Update comments and docstrings

mypyc/ir/ops.py

@@ -601,18 +601,15 @@ def __init__(
         extra_int_constants: list[tuple[int, RType]],
         priority: int,
     ) -> None:
-        # Each primitive much have a distint name, but otherwise they are arbitrary.
+        # Each primitive much have a distinct name, but otherwise they are arbitrary.
         self.name: Final = name
-        # If None, the argument is a compile-time type (RType).
         self.arg_types: Final = arg_types
-        # Result type; an int index i refers to the compile-type at arg_types[i].
-        # This allows simple type-safe generic operations.
         self.return_type: Final = return_type
         self.var_arg_type: Final = var_arg_type
         self.truncated_type: Final = truncated_type
         # If non-None, this will map to a call of a C helper function; if None,
-        # this will be a custom handler function that gets invoked during the lowering
-        # pass
+        # there must be a custom handler function that gets invoked during the lowering
+        # pass to generate low-level IR for the primitive (in the mypyc.lower package)
         self.c_function_name: Final = c_function_name
         self.error_kind: Final = error_kind
         self.steals: Final = steals
@@ -628,9 +625,10 @@ def __repr__(self) -> str:
 class PrimitiveOp(RegisterOp):
     """A higher-level primitive operation.
 
-    All of these have special compiler support. These will be lowered
-    (transformed) into lower-level ops before code generation, and after
-    reference counting op insertion.
+    Some of these have special compiler support. These will be lowered
+    (transformed) into lower-level IR ops before code generation, and after
+    reference counting op insertion. Others will be transformed into CallC
+    ops.
 
     Tagged integer equality is a typical primitive op with non-trivial
     lowering. It gets transformed into a tag check, followed by different

mypyc/irbuild/ll_builder.py

@@ -2003,8 +2003,10 @@ def primitive_op(
     ) -> Value:
         """Add a primitive op."""
         # Does this primitive map into calling a Python C API
-        # function, or an internal mypyc C API function?
+        # or an internal mypyc C API function?
         if desc.c_function_name:
+            # TODO: Generate PrimitiOps here and transform them into CallC
+            # ops only later in the lowering pass
             c_desc = CFunctionDescription(
                 desc.name,
                 desc.arg_types,
@@ -2022,7 +2024,7 @@ def primitive_op(
             return self.call_c(c_desc, args, line, result_type)
 
         # This primitve gets transformed in a lowering pass to
-        # lower-level IR ops using custom logic.
+        # lower-level IR ops using a custom transform function.
 
         coerced = []
         # Coerce fixed number arguments

mypyc/lower/registry.py

@@ -12,6 +12,8 @@
 
 
 def lower_binary_op(name: str) -> Callable[[LowerFunc], LowerFunc]:
+    """Register a handler that generates low-level IR for a primitive binary op."""
+
     def wrapper(f: LowerFunc) -> LowerFunc:
         assert name not in lowering_registry
         lowering_registry[name] = f

mypyc/primitives/registry.py

@@ -83,8 +83,6 @@ class LoadAddressDescription(NamedTuple):
 
 builtin_names: dict[str, tuple[RType, str]] = {}
 
-primitive_ops: dict[str, PrimitiveDescription] = {}
-
 
 def method_op(
     name: str,