Add doc/example (#133)

Author: kaihsin

src/kirin/dialects/fcf/stmts.py

@@ -21,9 +21,30 @@ class Foldr(ir.Statement):
 
 @statement(dialect=dialect)
 class Map(ir.Statement):
+    """Apply a given kernel function to every item of an iterable.
+
+    ## Example
+
+    ```python
+    from kirin.prelude import basic
+
+    @basic(typeinfer=True)
+    def myfunc(x: int):
+        return x*3
+
+    @basic(typeinfer=True)
+    def main():
+        return fcf.Map(fn=myfunc, coll=range(10))
+
+    ```
+    """
+
     fn: ir.SSAValue = info.argument(ir.types.PyClass(ir.Method))
+    """The kernel function to apply. The function should have signature `fn(x: int) -> Any`."""
     coll: ir.SSAValue = info.argument(ir.types.Any)
+    """The iterable to map over."""
     result: ir.ResultValue = info.result(ir.types.List)
+    """The list of results."""
 
 
 @statement(dialect=dialect)

src/kirin/interp/base.py

@@ -94,11 +94,11 @@ def run_method(
         This is defined by subclasses to describe what's the corresponding
         value of a method during the interpretation.
 
-        Args
+        Args:
             method (Method): the method to run.
             args (tuple[ValueType]): the arguments to the method, does not include self.
 
-        Returns
+        Returns:
             ValueType: the result of the method.
         """
         ...
@@ -108,12 +108,12 @@ def run_callable(
     ) -> MethodResult[ValueType]:
         """Run a callable statement.
 
-        Args
+        Args:
             code (Statement): the statement to run.
             args (tuple[ValueType]): the arguments to the statement,
                 includes self if the corresponding callable region contains a self argument.
 
-        Returns
+        Returns:
             ValueType: the result of the statement.
         """
         interface = code.get_trait(traits.CallableStmtInterface)
@@ -133,10 +133,13 @@ def run_callable_region(
         self, frame: FrameType, code: Statement, region: Region
     ) -> MethodResult[ValueType]:
         """A hook defines how to run the callable region given
-        the interpreter context. This is experimental API, don't
-        subclass it. The current reason of having it is mainly
-        because we need to dispatch back to the MethodTable for
-        emit.
+        the interpreter context.
+
+        Note:
+            This is experimental API, don't
+            subclass it. The current reason of having it is mainly
+            because we need to dispatch back to the MethodTable for
+            emit.
         """
         return self.run_ssacfg_region(frame, region)
 
@@ -149,8 +152,10 @@ def finalize(
         self, frame: FrameType, results: MethodResult[ValueType]
     ) -> MethodResult[ValueType]:
         """Postprocess a frame after it is popped from the stack. This is
-        called after a method is evaluated and the frame is popped. Default
-        implementation does nothing.
+        called after a method is evaluated and the frame is popped.
+
+        Note:
+            Default implementation does nothing.
         """
         return results
 
@@ -175,11 +180,10 @@ def permute_values(
         the given keyword arguments, where the keyword argument names
         refer to the last n arguments in the values tuple.
 
-        Args
-
-        mt: the method
-        values: the values tuple (should not contain method itself)
-        kwarg_names: the keyword argument names
+        Args:
+            arg_names: the argument names
+            values: the values tuple (should not contain method itself)
+            kwarg_names: the keyword argument names
         """
         n_total = len(values)
         if kwarg_names:
@@ -194,7 +198,32 @@ def permute_values(
         return args
 
     def run_stmt(self, frame: FrameType, stmt: Statement) -> StatementResult[ValueType]:
-        "run a statement within the current frame"
+        """Run a statement within the current frame
+
+        Args:
+            frame: the current frame
+            stmt: the statement to run
+
+        Returns:
+            StatementResult: the result of running the statement
+
+        Note:
+            In the case of implementing the fallback, subclass this method,
+            and filter the statement type you want to handle.
+
+        Example:
+            * implement an interpreter that only handles MyStmt:
+            ```python
+                class MyInterpreter(BaseInterpreter):
+                    ...
+                    def run_stmt(self, frame: FrameType, stmt: Statement) -> StatementResult[ValueType]:
+                        if isinstance(stmt, MyStmt):
+                            return self.run_my_stmt(frame, stmt)
+                        else:
+                            return ()
+            ```
+
+        """
         # TODO: update tracking information
         return self.eval_stmt(frame, stmt)
 

src/kirin/ir/dialect.py

@@ -18,13 +18,27 @@
 # TODO: add an option to generate default lowering at dialect construction
 @dataclass
 class Dialect:
-    """Dialect is a collection of statements, attributes, interpreters, lowerings, and codegen."""
+    """Dialect is a collection of statements, attributes, interpreters, lowerings, and codegen.
+
+    Example:
+        ```python
+            from kirin import ir
+
+            my_dialect = ir.Dialect(name="my_dialect")
+
+        ```
+    """
 
     name: str
+    """The name of the dialect."""
     stmts: list[type[Statement]] = field(default_factory=list, init=True)
+    """A list of statements in the dialect."""
     attrs: list[type[Attribute]] = field(default_factory=list, init=True)
+    """A list of attributes in the dialect."""
     interps: dict[str, MethodTable] = field(default_factory=dict, init=True)
+    """A dictionary of registered method table in the dialect."""
     lowering: dict[str, FromPythonAST] = field(default_factory=dict, init=True)
+    """A dictionary of registered python lowering implmentations in the dialect."""
 
     def __post_init__(self) -> None:
         from kirin.lowering.dialect import NoSpecialLowering
@@ -47,6 +61,31 @@ def register(self, node: type | None = None, key: str | None = None):
 
         Raises:
             ValueError: If the node is not a subclass of Statement, Attribute, DialectInterpreter, FromPythonAST, or DialectEmit.
+
+        Example:
+            * Register a method table for concrete interpreter (by default key="main") to the dialect:
+            ```python
+                from kirin import ir
+
+                my_dialect = ir.Dialect(name="my_dialect")
+
+                @my_dialect.register
+                class MyMethodTable(ir.MethodTable):
+                    ...
+            ```
+
+            * Register a method table for the interpreter specified by `key` to the dialect:
+            ```python
+                from kirin import ir
+
+                my_dialect = ir.Dialect(name="my_dialect")
+
+                @my_dialect.register(key="my_interp")
+                class MyMethodTable(ir.MethodTable):
+                    ...
+            ```
+
+
         """
         from kirin.interp.dialect import MethodTable
         from kirin.lowering.dialect import FromPythonAST

src/kirin/ir/group.py

@@ -200,19 +200,18 @@ def dialect_group(
         Callable[[RunPassGen[PassParams]], DialectGroup[PassParams]]: the dialect group.
 
     Example:
-
-    ```python
-    from kirin.dialects import cf, fcf, func, math
-
-    @dialect_group([cf, fcf, func, math])
-    def basic_no_opt(self):
-        # initializations
-        def run_pass(mt: Method) -> None:
-            # how passes are applied to the method
-            pass
-
-        return run_pass
-    ```
+        ```python
+        from kirin.dialects import cf, fcf, func, math
+
+        @dialect_group([cf, fcf, func, math])
+        def basic_no_opt(self):
+            # initializations
+            def run_pass(mt: Method) -> None:
+                # how passes are applied to the method
+                pass
+
+            return run_pass
+        ```
     """
 
     # NOTE: do not alias the annotation below