docs: fix some docstrings

midas/checker/builtins.py

@@ -26,7 +26,11 @@ Circular dependencies and diamond inheritance MUST be avoided
 
 
 def define_builtins(reg: TypesRegistry):
-    """Define builtin types and operations"""
+    """Define builtin types and operations
+
+    Args:
+        reg (TypesRegistry): the types registry
+    """
     any = reg.define_type("Any", TopType())
     unit = reg.define_type("None", UnitType())
     object = reg.define_type("object", BaseType(name="object"))

midas/checker/dispatcher.py

@@ -102,6 +102,11 @@ class CallDispatcher(Generic[E]):
         self.logger: logging.Logger = logging.getLogger("CallDispatcher")
 
     def set_reporter(self, reporter: FileReporter):
+        """Set the current reporter
+
+        Args:
+            reporter (FileReporter): the new file reporter
+        """
         self.reporter = reporter
 
     def get_result(
@@ -123,8 +128,8 @@ class CallDispatcher(Generic[E]):
         Args:
             location (Location): the call location
             callee (Type): the called function
-            positional (list[TypedExpr]): the list of positional arguments
+            positional (list[TypedExpr[E]]): the list of positional arguments
-            keywords (dict[str, TypedExpr]): the map of keyword arguments
+            keywords (dict[str, TypedExpr[E]]): the map of keyword arguments
             report_errors (bool, optional): whether type errors should be reported as diagnostics. Defaults to True.
 
         Returns:
@@ -250,7 +255,7 @@ class CallDispatcher(Generic[E]):
         """Check whether the passed argument types correspond to their matched parameter definitions
 
         Args:
-            arguments (list[MappedArgument]): the list of argument/parameter pairs
+            arguments (list[MappedArgument[E]]): the list of argument/parameter pairs
             report_errors (bool, optional): whether type errors should be reported as diagnostics. Defaults to True.
 
         Returns:
@@ -286,8 +291,8 @@ class CallDispatcher(Generic[E]):
         Args:
             overloads (list[Type]): the list of possible overloads
             location (Location): the call location
-            positional (list[TypedExpr]): the list of positional arguments
+            positional (list[TypedExpr[E]]): the list of positional arguments
-            keywords (dict[str, TypedExpr]): the map of keywords arguments
+            keywords (dict[str, TypedExpr[E]]): the map of keywords arguments
             report_errors (bool, optional): whether type errors should be reported as diagnostics. Defaults to True.
 
         Returns:
@@ -385,8 +390,8 @@ class CallDispatcher(Generic[E]):
         Args:
             function (Function): the function definition
             location (Location): the call location
-            positional (list[TypedExpr]): the list of positional arguments
+            positional (list[TypedExpr[E]]): the list of positional arguments
-            keywords (dict[str, TypedExpr]): the map of keyword arguments
+            keywords (dict[str, TypedExpr[E]]): the map of keyword arguments
             report_errors (bool, optional): whether type errors should be reported as diagnostics. Defaults to True.
 
         Returns:
@@ -514,8 +519,8 @@ class CallDispatcher(Generic[E]):
         function / a subtype of another.
 
         Args:
-            mapped1 (list[MappedArgument]): the first argument mappings (subtype)
+            mapped1 (list[MappedArgument[E]]): the first argument mappings (subtype)
-            mapped2 (list[MappedArgument]): the second argument mappings (supertype)
+            mapped2 (list[MappedArgument[E]]): the second argument mappings (supertype)
 
         Returns:
             bool: `True` if `mapped1` is a subtype of `mapped2`, `False` otherwise

midas/checker/evaluator.py

@@ -190,6 +190,7 @@ class Evaluator(m.Expr.Visitor[Any]):
         """Evaluate a predicate function call
 
         Args:
+            location (Location): the location of the call expression
             predicate (Predicate): the predicate to evaluate
             args (list[Any]): a list of positional arguments
             kwargs (dict[str, Any]): a map of keyword arguments
@@ -234,6 +235,7 @@ class Evaluator(m.Expr.Visitor[Any]):
         is set in the context using :func:`set_value` with the parameter's name
 
         Args:
+            location (Location): the location of the call expression
             function (Function): the called function
             args (list[Any]): a list of positional arguments
             kwargs (dict[str, Any]): a map of keyword arguments

midas/checker/frames/column_manager.py

@@ -45,7 +45,7 @@ class ColumnManager:
         Args:
             reporter (FileReporter): the file reporter to use for diagnostics
             location (Location): the subscript's location
-            column (DataFrameType): the column type
+            column (ColumnType): the column type
             index (TypedExpr): the index
 
         Returns:

midas/checker/frames/column_methods.py

@@ -353,10 +353,12 @@ class ColumnMethodRegistry(MethodRegistry[Call]):
             call (Call): the call object
             kwargs (list[Function.Parameter], optional): a list of extra
                 keyword-only parameters. Defaults to [].
-            formula (Callable[[Type], Formula], optional): optional formula
+            formula (Optional[Callable[[Type], Formula]], optional):
-                builder function to compute the return type. If set, the function
+                optional formula builder function to compute the return type.<br>
-                should accept the inner column type and return a formula.
+                If set, the function should accept the inner column type and
-                If `None`, the result is typed as `Column[Any]`. Defaults to None.
+                return a formula.<br>
+                If `None`, the result is typed as `Column[Any]`.
+                Defaults to None.
 
         Returns:
             Type: the result type

midas/checker/python.py

@@ -518,11 +518,12 @@ class PythonTyper(
     def _assign_attr(
         self, location: Location, object: p.Expr, name: str, value_type: Type
     ):
-        """Type check assignment to the given target
+        """Type check assignment to the given attribute target
 
         Args:
             location (Location): the location of the assignment
-            target (p.VariableExpr): the assignment's target
+            object (p.Expr): the target attribute's owner object
+            name (str): the target attribute's name
             value_type (Type): the value to be assigned
         """
         object_type: Type = self.type_of(object)
@@ -544,11 +545,15 @@ class PythonTyper(
         index: p.Expr,
         value_type: Type,
     ):
-        """Type check assignment to the given target
+        """Type check assignment to the given subscript target
 
         Args:
             location (Location): the location of the assignment
-            target (p.VariableExpr): the assignment's target
+            var (p.VariableExpr): the target subscript's owner. We only allow
+                a variable expression here because we might modify its type (for
+                example when assigning a column to a dataframe) and reference
+                types are not implemented
+            index (p.Expr): the target subscript's index expression
             value_type (Type): the value to be assigned
         """
         var_type: Type = self.type_of(var)
@@ -690,6 +695,20 @@ class PythonTyper(
         right: TypedExpr,
         method: str,
     ) -> Type:
+        """Compute the result type of a binary operation method call
+
+        This method is called for dunder methods called by binary operators
+
+        Args:
+            location (Location): the location of the operation
+            expr (p.Expr): the expression which triggered this resolution
+            left (TypedExpr): the left operand
+            right (TypedExpr): the right operand
+            method (str): the method name
+
+        Returns:
+            Type: the result type
+        """
         try:
             return self.call_method(
                 location=location,

midas/checker/reporter.py

@@ -70,6 +70,11 @@ class FileReporter:
 
     @contextmanager
     def with_context(self, ctx: str):
+        """Push given context for reports inside this manager and pop it on exit
+
+        Args:
+            ctx (str): the context to temporarily push on the stack
+        """
         self._context.append(ctx)
         try:
             yield