Add documentation to the player module

Signed-off-by: Olivier Gayot <olivier.gayot@sigexec.com>

1 files changed, 22 insertions, 2 deletions

diff --git a/cameltris/player.py b/cameltris/player.py
index cea5f38..aee2d58 100644
--- a/cameltris/player.py
+++ b/cameltris/player.py
@@ -1,3 +1,5 @@
+""" This module defines the Player class and some useful exceptions """
+
 import contextlib
 import random
 from typing import Optional
@@ -12,15 +14,18 @@ from .playfield import PlayField
 
 
 class WouldCollide(Exception):
-    pass
+    """ Exception that is raised when a piece collides with something else on
+    the play-field"""
 
 
 class PlayerQuit(Exception):
-    pass
+    """ Exception that is raised when a player decides to quit the game """
 
 
 class Player:
+    """ Class representing a player """
     def __init__(self, controller: Controller, starting_level: int):
+        """ Initialize the player """
         self.controller = controller
         self.playfield = PlayField()
 
@@ -43,6 +48,7 @@ class Player:
         self.level_canvas = pygame.Surface((296, 50))
 
     def generate_piece(self) -> tuple[Piece, list[int]]:
+        """ Generate a new piece and return it alongside its coordinates """
         # We may want to make this a function outside the class
         piece = random.choice((TPiece, SPiece, IPiece, ZPiece, SquarePiece, LPiece, JPiece))()
 
@@ -56,6 +62,8 @@ class Player:
         return (piece, [initial_y_position, initial_x_position])
 
     def lock_piece(self) -> None:
+        """ Lock a piece in its current position and trigger lines burning.
+        Can raise a WouldCollide exception """
         if self.has_collision(self.current_piece_position[0], self.current_piece_position[1]):
             raise WouldCollide()
 
@@ -93,6 +101,8 @@ class Player:
         self.refresh_piece_preview_canvas()
 
     def has_collision(self, y: int, x: int) -> bool:
+        """ Check if the current piece would collide with something else in the
+        playfield if it were placed on (y, x) """
         try:
             for row_id, row in enumerate(self.current_piece.elements):
                 for col_id, element in enumerate(row):
@@ -114,30 +124,35 @@ class Player:
         return False
 
     def move_piece_down(self) -> None:
+        """ Try to move the current piece down. Can raise a WouldCollide exception """
         if not self.has_collision(self.current_piece_position[0] + 1, self.current_piece_position[1]):
             self.current_piece_position[0] += 1
         else:
             raise WouldCollide()
 
     def move_piece_up(self) -> None:
+        """ Try to move the current piece up. Can raise a WouldCollide exception """
         if not self.has_collision(self.current_piece_position[0] - 1, self.current_piece_position[1]):
             self.current_piece_position[0] -= 1
         else:
             raise WouldCollide()
 
     def move_piece_left(self) -> None:
+        """ Try to move the current piece left. Can raise a WouldCollide exception """
         if not self.has_collision(self.current_piece_position[0], self.current_piece_position[1] - 1):
             self.current_piece_position[1] -= 1
         else:
             raise WouldCollide()
 
     def move_piece_right(self) -> None:
+        """ Try to move the current piece right. Can raise a WouldCollide exception """
         if not self.has_collision(self.current_piece_position[0], self.current_piece_position[1] + 1):
             self.current_piece_position[1] += 1
         else:
             raise WouldCollide()
 
     def rotate_piece_counter_clockwise(self) -> None:
+        """ Rotate the current piece counter-clockwise. Can raise a WouldCollide exception """
         self.current_piece.rotate_counter_clockwise()
 
         if self.has_collision(self.current_piece_position[0], self.current_piece_position[1]):
@@ -145,6 +160,7 @@ class Player:
             raise WouldCollide()
 
     def rotate_piece_clockwise(self) -> None:
+        """ Rotate the current piece clockwise. Can raise a WouldCollide exception """
         self.current_piece.rotate_clockwise()
 
         if self.has_collision(self.current_piece_position[0], self.current_piece_position[1]):
@@ -152,6 +168,7 @@ class Player:
             raise WouldCollide()
 
     def handle_input_pressed(self, event: pygame.event.Event) -> None:
+        """ Perform relevant actions based on input pressed """
         if self.controller.get_input_down(event) == Input.QUIT:
             raise PlayerQuit()
 
@@ -178,10 +195,12 @@ class Player:
                     self.lock_piece()
 
     def handle_input_released(self, event: pygame.event.Event) -> None:
+        """ Perform relevant action based on input released. """
         if self.controller.get_input_up(event) == Input.MOVE_DOWN:
             self.pressing_down_countdown = None
 
     def refresh_piece_preview_canvas(self) -> None:
+        """ Refresh the display of the next piece """
         self.piece_preview_canvas.fill(Color.black.value)
 
         non_empty_rows = list()
@@ -205,6 +224,7 @@ class Player:
                     self.piece_preview_canvas.blit(element, ((col_idx + x_offset) * 50 + 1, (row_idx + y_offset) * 50 + 1))
 
     def refresh_grid_canvas(self) -> None:
+        """ Refresh the display of the playfield """
         self.grid_canvas.fill(Color.black.value)
 
         for row_idx, row in enumerate(self.playfield.grid):