diff --git a/src/entities/background.py b/src/entities/background.py
index 6e1226ed..a3d82c0f 100644
--- a/src/entities/background.py
+++ b/src/entities/background.py
@@ -3,6 +3,17 @@
 
 
 class Background(Entity):
+    """
+    Represents the background entity in the FlapPyBird game.
+
+    This class is responsible for rendering the background image across the entire game window.
+
+    Args:
+        config (GameConfig): The game configuration object containing window dimensions and image resources.
+
+    Attributes:
+        Inherits all attributes from the Entity base class, including position and size.
+    """
     def __init__(self, config: GameConfig) -> None:
         super().__init__(
             config,
diff --git a/src/entities/entity.py b/src/entities/entity.py
index 6ec067ce..9cb2e754 100644
--- a/src/entities/entity.py
+++ b/src/entities/entity.py
@@ -6,6 +6,33 @@
 
 
 class Entity:
+    """
+    Represents a game entity with position, size, image, and collision detection.
+    Attributes:
+        config (GameConfig): Game configuration object containing settings and screen.
+        x (float): X-coordinate of the entity's top-left corner.
+        y (float): Y-coordinate of the entity's top-left corner.
+        w (int): Width of the entity.
+        h (int): Height of the entity.
+        image (Optional[pygame.Surface]): Image representing the entity.
+        hit_mask (Optional[list[list[bool]]]): Pixel-perfect collision mask.
+        Additional attributes can be set via kwargs.
+    Methods:
+        update_image(image, w=None, h=None):
+            Updates the entity's image, hit mask, and optionally its size.
+        cx:
+            Returns the X-coordinate of the entity's center.
+        cy:
+            Returns the Y-coordinate of the entity's center.
+        rect:
+            Returns a pygame.Rect representing the entity's position and size.
+        collide(other):
+            Checks for collision with another entity, using pixel-perfect collision if available.
+        tick():
+            Draws the entity and, if debug mode is enabled, draws its bounding box and position info.
+        draw():
+            Draws the entity's image on the screen if available.
+    """
     def __init__(
         self,
         config: GameConfig,
diff --git a/src/entities/floor.py b/src/entities/floor.py
index 95013f05..d70fe77d 100644
--- a/src/entities/floor.py
+++ b/src/entities/floor.py
@@ -3,6 +3,17 @@
 
 
 class Floor(Entity):
+    """
+    Represents the moving floor entity in the FlapPyBird game.
+    The Floor entity scrolls horizontally to simulate movement. It inherits from Entity and uses the base image.
+    The floor's position is updated in the `draw` method to create a looping effect, giving the illusion of continuous motion.
+    Attributes:
+        vel_x (int): The horizontal velocity of the floor.
+        x_extra (int): The extra width used for looping the floor image.
+    Methods:
+        stop(): Stops the floor's movement by setting its velocity to zero.
+        draw(): Updates the floor's position and draws it on the screen.
+    """
     def __init__(self, config: GameConfig) -> None:
         super().__init__(config, config.images.base, 0, config.window.vh)
         self.vel_x = 4
diff --git a/src/flappy.py b/src/flappy.py
index a8c87321..5b799580 100644
--- a/src/flappy.py
+++ b/src/flappy.py
@@ -18,6 +18,28 @@
 
 
 class Flappy:
+    """
+    Main class for the Flappy Bird game.
+    Handles game initialization, main loop, and transitions between game states:
+    splash screen, gameplay, and game over.
+    Attributes:
+        config (GameConfig): Configuration object containing game settings, resources, and state.
+    Methods:
+        __init__():
+            Initializes pygame, sets up the display, and loads game resources.
+        async start():
+            Main game loop. Cycles through splash, play, and game over states.
+        async splash():
+            Displays the welcome splash screen and waits for user input to start the game.
+        check_quit_event(event):
+            Checks for quit events (window close or escape key) and exits the game.
+        is_tap_event(event):
+            Determines if the user has tapped/clicked/flapped to interact with the game.
+        async play():
+            Runs the main gameplay loop, handling player movement, collision detection, and scoring.
+        async game_over():
+            Handles the game over state, animates the player crash, and waits for user input to restart.
+    """
     def __init__(self):
         pygame.init()
         pygame.display.set_caption("Flappy Bird")