Add doctests for create_canvas, run, and __judge_point

Added comprehensive doctests to Conway's Game of Life implementation.

Contributes to #9943

Author: adrian-cancio

cellular_automata/game_of_life.py

@@ -42,6 +42,27 @@
 
 
 def create_canvas(size: int) -> list[list[bool]]:
+    """
+    Create a square canvas of given size filled with False (dead cells).
+
+    Args:
+        size: The dimension of the square canvas
+
+    Returns:
+        A size x size 2D list of boolean values, all initialized to False
+
+    >>> canvas = create_canvas(3)
+    >>> len(canvas)
+    3
+    >>> len(canvas[0])
+    3
+    >>> all(all(not cell for cell in row) for row in canvas)
+    True
+    >>> create_canvas(1)
+    [[False]]
+    >>> create_canvas(0)
+    []
+    """
     canvas = [[False for i in range(size)] for j in range(size)]
     return canvas
 
@@ -54,15 +75,33 @@ def seed(canvas: list[list[bool]]) -> None:
 
 def run(canvas: list[list[bool]]) -> list[list[bool]]:
     """
-    This function runs the rules of game through all points, and changes their
-    status accordingly.(in the same canvas)
-    @Args:
-    --
-    canvas : canvas of population to run the rules on.
-
-    @returns:
-    --
-    canvas of population after one step
+    Run one generation of Conway's Game of Life on the canvas.
+
+    Applies the Game of Life rules to all cells simultaneously to produce
+    the next generation.
+
+    Args:
+        canvas: 2D list representing current state of cells
+
+    Returns:
+        2D list representing the next generation state
+
+    >>> blinker = [[False, False, False, False, False],
+    ...            [False, False, True, False, False],
+    ...            [False, False, True, False, False],
+    ...            [False, False, True, False, False],
+    ...            [False, False, False, False, False]]
+    >>> result = run(blinker)
+    >>> result[2]
+    [False, True, True, True, False]
+    >>> run([[False, False, False], [False, False, False], [False, False, False]])
+    [[False, False, False], [False, False, False], [False, False, False]]
+    >>> block = [[False, False, False, False],
+    ...          [False, True, True, False],
+    ...          [False, True, True, False],
+    ...          [False, False, False, False]]
+    >>> run(block)[1]
+    [False, True, True, False]
     """
     current_canvas = np.array(canvas)
     next_gen_canvas = np.array(create_canvas(current_canvas.shape[0]))
@@ -76,6 +115,43 @@ def run(canvas: list[list[bool]]) -> list[list[bool]]:
 
 
 def __judge_point(pt: bool, neighbours: list[list[bool]]) -> bool:
+    """
+    Apply Conway's Game of Life rules to determine the next state of a cell.
+
+    Args:
+        pt: Current state of the cell (True=alive, False=dead)
+        neighbours: 3x3 grid including the cell and its 8 neighbors
+
+    Returns:
+        The next state of the cell
+
+    Rules:
+        1. Live cell with <2 live neighbours dies (under-population)
+        2. Live cell with 2-3 live neighbours survives
+        3. Live cell with >3 live neighbours dies (over-population)
+        4. Dead cell with exactly 3 live neighbours becomes alive
+
+    >>> __judge_point(
+    ...     True, [[True, True, False], [False, True, False], [False, False, False]]
+    ... )
+    True
+    >>> __judge_point(
+    ...     True, [[True, False, False], [False, True, False], [False, False, False]]
+    ... )
+    False
+    >>> __judge_point(
+    ...     True, [[True, True, True], [True, True, False], [False, False, False]]
+    ... )
+    False
+    >>> __judge_point(
+    ...     False, [[True, True, False], [True, False, False], [False, False, False]]
+    ... )
+    True
+    >>> __judge_point(
+    ...     False, [[True, False, False], [False, False, False], [False, False, False]]
+    ... )
+    False
+    """
     dead = 0
     alive = 0
     # finding dead or alive neighbours count.