added docstrings to every file and function. (with claude, checked it)

tower and game_play dont meet pylint check yet.

game/util.py

@@ -1,49 +1,112 @@
-import pygame as pg
+"""Utility module - image loading, coordinate conversion, and sprite animation."""
 import os
+import pygame as pg
 
-img_path='assets/images'
+IMG_PATH='assets/images'
 WINDOW_SIZE=(800,600)
 
 def load_image(path, colorkey=(0,0,0)):
-    img = pg.image.load(img_path + path).convert()
+    """Load an image and set a colorkey for transparency.
+
+    Args:
+        path (str): Path to the image relative to ``IMG_PATH``.
+        colorkey (tuple[int,int,int]): RGB colour treated as transparent. Defaults to black.
+
+    Returns:
+        pg.Surface: The loaded and converted image.
+    """
+    img = pg.image.load(IMG_PATH + path).convert()
     img.set_colorkey(colorkey)
     return img
 
 def load_images(dir_path):
+    """Load all images from a directory using colorkey transparency.
+
+    Args:
+        dir_path (str): Directory path relative to ``IMG_PATH``.
+
+    Returns:
+        list[pg.Surface]: All images found in the directory, in filesystem order.
+    """
     images = []
-    for img_name in os.listdir(img_path + dir_path):
+    for img_name in os.listdir(IMG_PATH + dir_path):
         images.append(load_image(dir_path + '/' + img_name))
     return images
 
 def load_image_alpha(path):
-    img = pg.image.load(img_path + path).convert_alpha()
+    """Load an image preserving its alpha channel.
+
+    Args:
+        path (str): Path to the image relative to ``IMG_PATH``.
+
+    Returns:
+        pg.Surface: The loaded image with per-pixel alpha.
+    """
+    img = pg.image.load(IMG_PATH + path).convert_alpha()
     return img
 
 def load_images_alpha(dir_path):
+    """Load all images from a directory, preserving alpha channels.
+
+    Args:
+        dir_path (str): Directory path relative to ``IMG_PATH``.
+
+    Returns:
+        list[pg.Surface]: All images found in the directory, in filesystem order.
+    """
     images = []
-    for img_name in os.listdir(img_path + dir_path):
+    for img_name in os.listdir(IMG_PATH + dir_path):
         images.append(load_image_alpha(dir_path + '/' + img_name))
     return images
 
 def tile_to_pixel(waypoint, tile_size, center=False):
+    """Convert a tile grid position to world-space pixel coordinates.
+
+    Args:
+        tile_pos (tuple[int, int]): Grid position ``(x, y)``.
+        tile_size (int): Width and height of a single tile in pixels.
+        center (bool): If ``True``, return the centre of the tile. Defaults to ``False``.
+
+    Returns:
+        tuple[int, int]: Pixel position ``(x, y)``.
+    """
     if center:
         return (
             waypoint[0] * tile_size + tile_size // 2,
             waypoint[1] * tile_size + tile_size // 2
             )
-    else:
-        return (
-            waypoint[0] * tile_size,
-            waypoint[1] * tile_size
-        )
+
+    return (
+        waypoint[0] * tile_size,
+        waypoint[1] * tile_size
+    )
 
 def pixel_to_tile(waypoint, tile_size):
+    """Convert a world-space pixel position to tile grid coordinates.
+
+    Args:
+        pixel_pos (tuple[float, float]): Pixel position ``(x, y)``.
+        tile_size (int): Width and height of a single tile in pixels.
+
+    Returns:
+        tuple[float, float]: Fractional tile position ``(x, y)``.
+    """
     return (
         waypoint[0] / tile_size,
         waypoint[1] / tile_size
         )
 
 class Animation:
+    """Frame-based sprite animation with optional looping and manual play control.
+
+    Attributes:
+        images (list[pg.Surface]): Ordered list of animation frames.
+        loop (bool): Whether the animation loops continuously.
+        img_duration (int): Number of update ticks each frame is shown for.
+        done (bool): ``True`` once a non-looping animation has finished.
+        frame (int): Current tick counter used to derive the active frame index.
+        playing (bool): Whether the animation is currently advancing.
+    """
     def __init__(self, images, img_dur=5, loop=True):
         self.images = images
         self.loop = loop
@@ -53,9 +116,15 @@ class Animation:
         self.playing = False  # not playing until told to
 
     def copy(self):
+        """Return a fresh copy of this animation, reset to its initial state.
+
+        Returns:
+            Animation: A new Animation sharing the same images and settings.
+        """
         return Animation(self.images, self.img_duration, self.loop)
-    
+
     def update(self):
+        """Advance the animation by one tick if it is currently playing."""
         if not self.playing:
             return
 
@@ -68,9 +137,15 @@ class Animation:
                 self.playing = False
 
     def play_animation(self):
+        """Start the animation from the first frame."""
         self.playing = True
         self.done = False
         self.frame = 0
-    
+
     def img(self):
-        return self.images[self.frame // self.img_duration]
+        """Return the image for the current tick.
+
+        Returns:
+            pg.Surface: The active animation frame.
+        """
+        return self.images[self.frame // self.img_duration]