add docstrings

Author: mariuzka

src/mesarcade/artist.py

@@ -218,8 +218,26 @@ def update(self):
 
 
 class CellAgentArtists(Artist):
-    """
-    A visual representation of CellAgents.
+    """Renders agents on a cell-based grid space.
+
+    Visualizes agents that live on cells.
+    Each agent is drawn at its cell's coordinate position.
+
+    Args:
+        color: Default color for all entities. Used when color_attribute is None.
+        color_attribute: Agent attribute name or callable to determine color.
+        color_map: Matplotlib colormap name or dict mapping values to colors.
+        color_vmin: Minimum value for colormap normalization.
+        color_vmax: Maximum value for colormap normalization.
+        shape: Entity shape, either "rect" or "circle".
+        size: Size multiplier relative to cell size. Defaults to 1.
+        filter_entities: Callable to filter which agents are displayed.
+        jitter: If True, adds random offset to prevent overlap.
+        dynamic_color: If True, updates colors each frame.
+        dynamic_position: If True, updates positions each frame.
+        dynamic_population: If True, handles agents being added/removed.
+        get_population: Callable returning the agent collection from model.
+        get_xy_position: Callable returning (x, y) position for an agent.
     """
 
     def __init__(
@@ -266,8 +284,26 @@ def scale_y(self, y):
 
 
 class CellArtists(Artist):
-    """
-    A visual representation of Cells.
+    """Renders cells of a grid space.
+
+    Visualizes the cells themselves (not agents on them). Useful for displaying
+    cell properties like terrain type, resource levels, or other cell attributes.
+
+    Args:
+        color: Default color for all cells. Used when color_attribute is None.
+        color_attribute: Cell attribute name or callable to determine color.
+        color_map: Matplotlib colormap name or dict mapping values to colors.
+        color_vmin: Minimum value for colormap normalization.
+        color_vmax: Maximum value for colormap normalization.
+        shape: Cell shape, either "rect" or "circle".
+        size: Size multiplier relative to cell size. Defaults to 1.
+        filter_entities: Callable to filter which cells are displayed.
+        jitter: If True, adds random offset to cell positions.
+        dynamic_color: If True, updates colors each frame.
+        dynamic_position: If True, updates positions each frame.
+        dynamic_population: If True, handles cells being added/removed.
+        get_population: Callable returning the cell collection from model.
+        get_xy_position: Callable returning (x, y) position for a cell.
     """
 
     def __init__(
@@ -312,8 +348,26 @@ def scale_y(self, y):
 
 
 class ContinuousSpaceAgentArtists(Artist):
-    """
-    A visual representation of ContinuousSpaceAgents.
+    """Renders agents in a continuous space.
+
+    Visualizes agents that move freely in continuous 2D space rather than
+    on a discrete grid. Positions are scaled to fit the plot area.
+
+    Args:
+        color: Default color for all agents. Used when color_attribute is None.
+        color_attribute: Agent attribute name or callable to determine color.
+        color_map: Matplotlib colormap name or dict mapping values to colors.
+        color_vmin: Minimum value for colormap normalization.
+        color_vmax: Maximum value for colormap normalization.
+        shape: Agent shape, either "rect" or "circle".
+        size: Size multiplier for agent sprites. Defaults to 2.
+        filter_entities: Callable to filter which agents are displayed.
+        jitter: If True, adds random offset to prevent overlap.
+        dynamic_color: If True, updates colors each frame.
+        dynamic_position: If True, updates positions each frame.
+        dynamic_population: If True, handles agents being added/removed.
+        get_population: Callable returning the agent collection from model.
+        get_xy_position: Callable returning (x, y) position for an agent.
     """
 
     def __init__(
@@ -358,6 +412,28 @@ def scale_y(self, y):
 
 
 class NetworkCellArtists(Artist):
+    """Renders nodes and edges of a network graph.
+
+    Visualizes cells as nodes in a network layout.
+
+    Args:
+        color: Default color for all nodes. Used when color_attribute is None.
+        color_attribute: Cell attribute name or callable to determine color.
+        color_map: Matplotlib colormap name or dict mapping values to colors.
+        color_vmin: Minimum value for colormap normalization.
+        color_vmax: Maximum value for colormap normalization.
+        shape: Node shape, either "rect" or "circle".
+        size: Size multiplier for node sprites. Defaults to 2.
+        filter_entities: Callable to filter which nodes are displayed.
+        jitter: If True, adds random offset to node positions.
+        dynamic_color: If True, updates colors each frame.
+        dynamic_position: If True, updates positions each frame.
+        dynamic_population: If True, handles nodes being added/removed.
+        networkx_layout: Layout function from networkx (e.g., spring_layout).
+        get_population: Callable returning the cell collection from model.
+        get_xy_position: Callable returning (x, y) position for a cell.
+    """
+
     def __init__(
         self,
         color: Color = "black",
@@ -447,6 +523,28 @@ def draw(self):
 
 
 class NetworkAgentArtists(NetworkCellArtists):
+    """Renders agents on a network graph.
+
+    Visualizes agents that live on network nodes.
+
+    Args:
+        color: Default color for all agents. Used when color_attribute is None.
+        color_attribute: Agent attribute name or callable to determine color.
+        color_map: Matplotlib colormap name or dict mapping values to colors.
+        color_vmin: Minimum value for colormap normalization.
+        color_vmax: Maximum value for colormap normalization.
+        shape: Agent shape, either "rect" or "circle".
+        size: Size multiplier for agent sprites. Defaults to 2.
+        filter_entities: Callable to filter which agents are displayed.
+        jitter: If True, adds random offset to prevent overlap.
+        dynamic_color: If True, updates colors each frame.
+        dynamic_position: If True, updates positions each frame.
+        dynamic_population: If True, handles agents being added/removed.
+        networkx_layout: Layout function from networkx (e.g., spring_layout).
+        get_population: Callable returning the agent collection from model.
+        get_xy_position: Callable returning (x, y) position for an agent.
+    """
+
     def __init__(
         self,
         color: Color = "black",

src/mesarcade/canvas.py

@@ -14,7 +14,25 @@
 
 
 class Canvas:
-    """The main GUI window."""
+    """The main GUI window for visualizing mesa agent-based models.
+
+    Creates an interactive window that displays plots, controls, and value
+    displays for a mesa simulation. Call show() to start the visualization.
+
+    Args:
+        model_class: The mesa model class to instantiate and visualize.
+        plots: List of plots (e.g., GridSpacePlot, ModelHistoryPlot) to display.
+            Maximum 4 plots supported.
+        controllers: List of controllers (NumController, CatController) for
+            adjusting model parameters interactively.
+        value_displays: List of ValueDisplay instances showing model metrics.
+        window_width: Window width in pixels. Height is calculated as 60% of
+            width. Defaults to 1200.
+        window_title: Title shown in the window title bar. Defaults to "mesarcade".
+        target_fps: Target frames per second for animation. Defaults to 40.
+        rendering_step: Number of simulation steps between visual updates.
+            Defaults to 1.
+    """
 
     def __init__(
         self,
@@ -28,33 +46,6 @@ def __init__(
         rendering_step: int = 1,
         _visible: bool = True,
     ) -> None:
-        """ "
-        Creates a new canvas instance.
-
-        Args:
-            model_class (type[mesa.Model]):
-                The mesa model class.
-            plots (list, optional):
-                The list of controllers that should be placed in the canvas.
-                Currently, the maximum number of plots is 4.
-                Defaults to [].
-            controllers (list, optional):
-                The list of controllers that should be placed in the canvas.
-                Defaults to [].
-            window_width (int, optional):
-                The width of the canvas window in pixels.
-                Determines the height of the canvas.
-                Defaults to 1200.
-            window_title (str, optional):
-                The title of the canvas.
-                Defaults to "mesarcade".
-            target_fps (int, optional):
-                The number of frames per second (FPS) that the animations should show.
-                Defaults to 40.
-            rendering_step (int, optional):
-                The number of simulation steps until the visualizations are rerendered.
-                Defaults to 1.
-        """
         window_height = int(window_width * 0.6)
 
         if not arcade.timings_enabled():

src/mesarcade/controller.py

@@ -54,6 +54,18 @@ def calculate_align_y(self, i):
 
 
 class CatController(_Controller):
+    """A dropdown controller for categorical model parameters.
+
+    Displays a dropdown menu allowing users to select from predefined options
+    during the simulation.
+
+    Args:
+        parameter_name: Name of the model parameter to control.
+        parameter_value: Initial value of the parameter.
+        parameter_options: List of allowed values for the dropdown.
+        label: Optional display label. If None, parameter_name is used.
+    """
+
     def __init__(
         self,
         parameter_name: str,
@@ -86,6 +98,20 @@ def setup(self, i):
 
 
 class NumController(_Controller):
+    """A slider controller for numeric model parameters.
+
+    Displays a slider with +/- buttons allowing users to adjust numeric
+    parameters within a defined range during the simulation.
+
+    Args:
+        parameter_name: Name of the model parameter to control.
+        parameter_value: Initial value of the parameter.
+        min_value: Minimum allowed value.
+        max_value: Maximum allowed value.
+        step: Increment/decrement step size.
+        label: Optional display label. If None, parameter_name is used.
+    """
+
     def __init__(
         self,
         parameter_name: str,

src/mesarcade/history_plot.py

@@ -282,19 +282,37 @@ def draw(self):
 
 
 class ModelHistoryPlot(Figure):
+    """A line plot that displays the history of model attributes over time.
+
+    Tracks one or more model attributes and visualizes their values as lines
+    over the course of the simulation. Supports up to 6 lines.
+
+    Args:
+        model_attributes: List of model attributes to track. Each element can be
+            a string (attribute name) or a callable that takes a mesa.Model and
+            returns a numeric value.
+        labels: Optional labels for the legend. If None, attribute names are
+            used for string attributes, or "no label" for callables.
+        colors: Optional colors for the lines. Accepts color names, RGB tuples,
+            or RGBA tuples. Defaults to a predefined color palette.
+        legend: Whether to display a legend. Defaults to True.
+        title: Optional title for the plot.
+        from_datacollector: If True, reads values from the model's datacollector
+            instead of directly from model attributes. Only works with string
+            attributes. Defaults to False.
+        rendering_step: Simulation steps between plot updates. Defaults to 3.
+    """
+
     def __init__(
         self,
-        model_attributes: str | list[str],
+        model_attributes: list[str],
         labels: list[str] | None = None,
         colors: list[Color] | None = None,
         legend: bool = True,
         title: str | None = None,
         from_datacollector: bool = False,
         rendering_step: int = 3,
     ) -> None:
-        if not isinstance(model_attributes, (list, tuple)):
-            model_attributes = [model_attributes]
-
         plot = _ModelHistoryPlot(
             model_attributes=model_attributes,
             labels=labels,

src/mesarcade/space_plot.py

@@ -10,6 +10,18 @@
 
 
 class GridSpacePlot(Figure):
+    """A plot for visualizing cell-based grid spaces.
+
+    Displays agents and/or cells on a discrete grid. The grid dimensions
+    are automatically determined from the space.
+
+    Args:
+        artists: Artist(s) defining how to render entities (e.g., CellAgentArtists).
+        background_color: Background color of the plot area.
+        title: Optional title displayed above the plot.
+        get_space: Callable returning the grid space from the model.
+    """
+
     def __init__(
         self,
         artists: Artist | list[Artist] = [],
@@ -30,6 +42,18 @@ def __init__(
 
 
 class ContinuousSpacePlot(Figure):
+    """A plot for visualizing continuous 2D spaces.
+
+    Displays agents that move freely in continuous space. Agent positions
+    are scaled to fit the plot area based on the space dimensions.
+
+    Args:
+        artists: Artist(s) defining how to render entities (e.g., ContinuousSpaceAgentArtists).
+        background_color: Background color of the plot area.
+        title: Optional title displayed above the plot.
+        get_space: Callable returning the continuous space from the model.
+    """
+
     def __init__(
         self,
         artists: Artist | list[Artist] = [],
@@ -50,6 +74,18 @@ def __init__(
 
 
 class NetworkPlot(Figure):
+    """A plot for visualizing network/graph-based spaces.
+
+    Displays agents and/or nodes on a network graph. Node positions are
+    computed using a networkx layout algorithm specified in the artist.
+
+    Args:
+        artists: Artist(s) defining how to render entities (e.g., NetworkCellArtists).
+        background_color: Background color of the plot area.
+        title: Optional title displayed above the plot.
+        get_space: Callable returning the network grid from the model.
+    """
+
     def __init__(
         self,
         artists: Artist | list[Artist] = [],

src/mesarcade/value_display.py

@@ -10,20 +10,30 @@
 
 
 class ValueDisplay:
+    """Displays the current value of a model attribute in the GUI.
+
+    Shows a labeled value that updates during the simulation. Useful for
+    displaying key metrics like population counts, resource levels, or
+    any other scalar value derived from the model.
+
+    Args:
+        model_attribute: The attribute to display. Can be a string (attribute
+            name) or a callable that takes a mesa.Model and returns a value.
+        label: Optional label text. If None, the attribute name is used for
+            string attributes, or "no label" for callables.
+        update_step: Simulation steps between value updates. Defaults to 10.
+        from_datacollector: If True, reads values from the model's datacollector
+            instead of directly from the model. Only works with string
+            attributes. Defaults to False.
+    """
+
     def __init__(
         self,
         model_attribute: str | Callable[[mesa.Model], Any] | None,
         label: str | None = None,
         update_step: int = 10,
         from_datacollector: bool = False,
     ) -> None:
-        """Displays the value of a given model attribute.
-
-        Args:
-            model_attribute (str | None, optional): The model attribute. Defaults to None.
-            label (str | None, optional): An optional label for the model attribute. Defaults to None.
-            update_step (int, optional): The number of steps after which the displayed value gets updated. Defaults to 10.
-        """
         self.model_attribute = model_attribute
         self.label = label
         self.update_step = update_step