improvement: documentation of parameters as show in the completion box

frontend/src/core/codemirror/language/python.ts

@@ -78,7 +78,12 @@ const lspClient = once((lspConfig: LSPConfig) => {
           enabled: true,
         },
         jedi: {
-          auto_import_modules: ["marimo", "numpy"],
+          // Modules which should be imported and use compile-time, rather
+          // than static analysis; this is a trade-off between being able
+          // to access more information set on runtime (e.g. via setattr)
+          // vs being able to read the information from the source code
+          // (e.g. comments with documentation for attributes).
+          auto_import_modules: ["numpy"],
         },
         jedi_completion: {
           // Ensure that parameters are included for completion snippets.

marimo/_ai/_types.py

@@ -68,11 +68,22 @@ class ChatMessage:
 
 @dataclass
 class ChatModelConfig:
+    # Maximum number of tokens.
     max_tokens: Optional[int] = None
+
+    # Temperature for the model (randomness).
     temperature: Optional[float] = None
+
+    # Restriction on the cumulative probability of prediction candidates.
     top_p: Optional[float] = None
+
+    # Number of top prediction candidates to consider.
     top_k: Optional[int] = None
+
+    # Penalty for tokens which appear frequently.
     frequency_penalty: Optional[float] = None
+
+    # Penalty for tokens which already appeared at least once.
     presence_penalty: Optional[float] = None
 
 

marimo/_ai/llm/_impl.py

@@ -27,10 +27,9 @@ class simple(ChatModel):
     Convenience class for wrapping a ChatModel or callable to
     take a single prompt
 
-    **Args:**
-
-    - delegate: A callable that takes a
-        single prompt and returns a response
+    Args:
+        delegate: A callable that takes a
+            single prompt and returns a response
     """
 
     def __init__(self, delegate: Callable[[str], object]):
@@ -48,15 +47,14 @@ class openai(ChatModel):
     """
     OpenAI ChatModel
 
-    **Args:**
-
-    - model: The model to use.
-        Can be found on the [OpenAI models page](https://platform.openai.com/docs/models)
-    - system_message: The system message to use
-    - api_key: The API key to use.
-        If not provided, the API key will be retrieved
-        from the OPENAI_API_KEY environment variable or the user's config.
-    - base_url: The base URL to use
+    Args:
+        model: The model to use.
+            Can be found on the [OpenAI models page](https://platform.openai.com/docs/models)
+        system_message: The system message to use
+        api_key: The API key to use.
+            If not provided, the API key will be retrieved
+            from the OPENAI_API_KEY environment variable or the user's config.
+        base_url: The base URL to use
     """
 
     def __init__(
@@ -160,16 +158,15 @@ class anthropic(ChatModel):
     """
     Anthropic ChatModel
 
-    **Args:**
-
-    - model: The model to use.
-        Can be found on the [Anthropic models page](https://docs.anthropic.com/en/docs/about-claude/models)
-    - system_message: The system message to use
-    - api_key: The API key to use.
-        If not provided, the API key will be retrieved
-        from the ANTHROPIC_API_KEY environment variable
-        or the user's config.
-    - base_url: The base URL to use
+    Args:
+        model: The model to use.
+            Can be found on the [Anthropic models page](https://docs.anthropic.com/en/docs/about-claude/models)
+        system_message: The system message to use
+        api_key: The API key to use.
+            If not provided, the API key will be retrieved
+            from the ANTHROPIC_API_KEY environment variable
+            or the user's config.
+        base_url: The base URL to use
     """
 
     def __init__(
@@ -258,15 +255,14 @@ class google(ChatModel):
     """
     Google AI ChatModel
 
-    **Args:**
-
-    - model: The model to use.
-        Can be found on the [Gemini models page](https://ai.google.dev/gemini-api/docs/models/gemini)
-    - system_message: The system message to use
-    - api_key: The API key to use.
-        If not provided, the API key will be retrieved
-        from the GOOGLE_AI_API_KEY environment variable
-        or the user's config.
+    Args:
+        model: The model to use.
+            Can be found on the [Gemini models page](https://ai.google.dev/gemini-api/docs/models/gemini)
+        system_message: The system message to use
+        api_key: The API key to use.
+            If not provided, the API key will be retrieved
+            from the GOOGLE_AI_API_KEY environment variable
+            or the user's config.
     """
 
     def __init__(
@@ -338,15 +334,14 @@ class groq(ChatModel):
     """
     Groq ChatModel
 
-    **Args:**
-
-    - model: The model to use.
-        Can be found on the [Groq models page](https://console.groq.com/docs/models)
-    - system_message: The system message to use
-    - api_key: The API key to use.
-        If not provided, the API key will be retrieved
-        from the GROQ_API_KEY environment variable or the user's config.
-    - base_url: The base URL to use
+    Args:
+        model: The model to use.
+            Can be found on the [Groq models page](https://console.groq.com/docs/models)
+        system_message: The system message to use
+        api_key: The API key to use.
+            If not provided, the API key will be retrieved
+            from the GROQ_API_KEY environment variable or the user's config.
+        base_url: The base URL to use
     """
 
     def __init__(

marimo/_islands/_island_generator.py

@@ -29,6 +29,17 @@
 
 
 class MarimoIslandStub:
+    """
+    Args:
+        display_code: Whether to display code.
+        display_output: Whether to display output.
+        is_reactive: Whether it is reactive.
+        cell_id: Cell identifier.
+        app_id: App identifier.
+        app_id: App identifier.
+        code: Code.
+    """
+
     def __init__(
         self,
         display_code: bool = False,
@@ -156,8 +167,7 @@ class MarimoIslandGenerator:
     3. Replace all code snippets with the rendered HTML.
     4. Include the header in the <head> tag.
 
-    # Example
-
+    Examples:
     Using the MarimoIslandGenerator class:
     ```python
     import asyncio
@@ -214,6 +224,8 @@ async def main():
         f.write(html)
     ```
 
+    Args:
+        app_id: The optional identifier of the app, defaults to `main`.
     """
 
     def __init__(self, app_id: str = "main"):

marimo/_output/data/data.py

@@ -85,13 +85,11 @@ def arrow(data: bytes) -> VirtualFile:
 def parquet(data: bytes) -> VirtualFile:
     """Create a virtual file for Parquet data.
 
-    **Args.**
-
-    - data: Parquet data in bytes
-
-    **Returns.**
+    Args:
+        data: Parquet data in bytes
 
-    A `VirtualFile` object.
+    Returns:
+        A `VirtualFile` object.
     """
     return any_data(data, ext="parquet")  # type: ignore
 

marimo/_output/justify.py

@@ -8,6 +8,9 @@
 def center(item: object) -> Html:
     """Center an item.
 
+    Args:
+        item: object to center.
+
     Returns:
         A centered `Html` object.
     """
@@ -18,6 +21,9 @@ def center(item: object) -> Html:
 def left(item: object) -> Html:
     """Left-justify an item.
 
+    Args:
+        item: object to left-justify.
+
     Returns:
         A left-justified `Html` object.
     """
@@ -28,6 +34,9 @@ def left(item: object) -> Html:
 def right(item: object) -> Html:
     """Right-justify an item.
 
+    Args:
+        item: object to right-justify.
+
     Returns:
         A right-justified `Html` object.
     """

marimo/_output/md.py

@@ -209,13 +209,11 @@ def md(text: str) -> Html:
     $$
 
 
-    **Args**:
+    Args:
+        text: a string of markdown
 
-    - `text`: a string of markdown
-
-    **Returns**:
-
-    - An `Html` object.
+    Returns:
+        An `Html` object.
     """
     return _md(text)
 
@@ -237,11 +235,11 @@ def latex(*, filename: Union[str, Path]) -> None:
     mo.latex(filename="https://example.com/macros.tex")
     ```
 
-    **Args**:
-    - `filename`: Path to a LaTeX file
+    Args:
+        filename: Path to a LaTeX file
 
-    **Returns**:
-    - An `Html` object
+    Returns:
+        An `Html` object
     """
 
     if isinstance(filename, Path):

marimo/_output/show_code.py

@@ -69,17 +69,15 @@ def factorial(n: int) -> int:
     mo.show_code()
     ```
 
-    **Args:**
-
-    - `output`: the output to display with the cell's code; omit the output
-      to just show the cell's code.
-    - `position`: Where to display the code relative to the output.
-      Use "above" to show code above the output, or "below" (default) to show
-      code below the output.
-
-    **Returns:**
-
-    HTML of the `output` arg displayed with its code.
+    Args:
+        output: the output to display with the cell's code; omit the output
+            to just show the cell's code.
+        position: Where to display the code relative to the output.
+            Use "above" to show code above the output, or "below" (default) to show
+            code below the output.
+
+    Returns:
+        HTML of the `output` arg displayed with its code.
     """
     assert position in ["above", "below"], (
         "position must be 'above' or 'below'"

marimo/_plugins/ui/_impl/data_editor.py

@@ -135,6 +135,8 @@ class data_editor(
         on_change (Optional[Callable]): Optional callback to run when this element's value changes.
         column_sizing_mode (Literal["auto", "fit"]): The column sizing mode for the table.
             `auto` will size columns based on the content, `fit` will size columns to fit the view.
+        pagination (Optional[bool]): Whether to use pagination, enabled by default.
+        page_size (Optional[int]): Page size if pagination is in use, 50 by default.
     """
 
     _name: Final[str] = "marimo-data-editor"

marimo/_plugins/ui/_impl/data_explorer.py

@@ -27,6 +27,8 @@ class data_explorer(UIElement[dict[str, Any], dict[str, Any]]):
 
     Args:
         df (IntoDataFrame): The DataFrame to visualize.
+        on_change (Callable[[dict[str, object]], None], optional): Optional callback
+            to run when this element's value changes.
     """
 
     _name: Final[str] = "marimo-data-explorer"

marimo/_plugins/ui/_impl/dictionary.py

@@ -91,6 +91,8 @@ class dictionary(_batch_base):
         elements (dict[str, UIElement[Any, Any]]): A dict mapping names to UI
             elements to include.
         label (str, optional): A descriptive name for the dictionary. Defaults to "".
+        on_change (Callable[[dict[str, object]], None], optional): Optional callback
+            to run when this element's value changes.
     """
 
     def __init__(

marimo/_plugins/ui/_impl/table.py

@@ -279,7 +279,7 @@ def style_cell(_rowId, _columnName, value):
         selection (Literal["single", "multi", "single-cell", "multi-cell"], optional): 'single' or 'multi' to enable row selection,
             'single-cell' or 'multi-cell' to enable cell selection
             or None to disable. Defaults to "multi".
-        initial_selection (Union[List[int], List[tuple[str, str]), optional): Indices of the rows you want selected by default.
+        initial_selection (Union[List[int], List[tuple[str, str]], optional): Indices of the rows you want selected by default.
         page_size (int, optional): The number of rows to show per page. Defaults to 10.
         show_column_summaries (Union[bool, Literal["stats", "chart"]], optional): Whether to show column summaries.
             Defaults to True when the table has less than 40 columns and at least 10 rows, False otherwise.
@@ -299,6 +299,7 @@ def style_cell(_rowId, _columnName, value):
         style_cell (Callable[[str, str, Any], Dict[str, Any]], optional): A function that takes the row id, column name and value and returns a dictionary of CSS styles.
         max_columns (int, optional): Maximum number of columns to display. Defaults to 50.
             Set to None to show all columns.
+        label (str, optional): A descriptive name for the table. Defaults to "".
     """
 
     _name: Final[str] = "marimo-table"

marimo/_plugins/ui/_impl/tabs.py

@@ -48,6 +48,9 @@ class tabs(UIElement[str, str]):
         lazy (bool, optional): Whether to lazily load the tab content.
             This is a convenience that wraps each tab in a `mo.lazy`
             component. Defaults to False.
+        label (str, optional): A descriptive name for the tab. Defaults to "".
+        on_change (Callable[[dict[str, object]], None], optional): Optional callback
+            to run when this element's value changes.
     """
 
     _name: Final[str] = "marimo-tabs"

marimo/_runtime/complete.py

@@ -495,13 +495,12 @@ def completion_worker(
     """Code completion worker.
 
 
-    **Args:**
-
-    - `completion_queue`: queue from which requests are pulled.
-    - `graph`: dataflow graph backing the marimo program
-    - `glbls`: dictionary of global variables in interpreter memory
-    - `glbls_lock`: lock protecting globals
-    - `stream`: stream used to communicate completion results
+    Args:
+        completion_queue: queue from which requests are pulled.
+        graph: dataflow graph backing the marimo program
+        glbls: dictionary of global variables in interpreter memory
+        glbls_lock: lock protecting globals
+        stream: stream used to communicate completion results
     """
 
     while True:

marimo/_runtime/control_flow.py

@@ -16,6 +16,9 @@ class MarimoStopError(BaseException):
 
     Inherits from `BaseException` to prevent accidental capture with
     `except Exception` (similar to `KeyboardInterrupt`)
+
+    Args:
+        output: optional output object
     """
 
     def __init__(self, output: Optional[object]) -> None:
@@ -37,6 +40,10 @@ def stop(predicate: bool, output: Optional[object] = None) -> None:
         mo.stop(form.value is None, mo.md("**Submit the form to continue.**"))
         ```
 
+    Args:
+        predicate (bool): The predicate indicating whether to stop.
+        output (bool): The output to be assigned to the current cell.
+
     Raises:
         MarimoStopError: When `predicate` is `True`
     """