update documentation

Author: ng-lis

projects/Snake Game/src/display.py

@@ -3,6 +3,7 @@
 
 
 class Display:
+    """Manages the display of the game."""
     def __init__(self):
         pygame.init()
         self.width = GameSettings.WIDTH
@@ -13,6 +14,14 @@ def __init__(self):
         self.clock = pygame.time.Clock()
 
     def update_ui(self, snake, food, score, high_score):
+        """Updates the UI with the current game state.
+
+        Args:
+            snake (Snake): The snake object that contains the snake body (Snake.blocks).
+            food (Point): The food object to be displayed.
+            score (int): The current game score.
+            high_score: The highest score achieved so far.
+        """
         self.window.fill(RgbColors.BLACK)
         self.draw_snake(snake)
         self.draw_food(food)
@@ -40,7 +49,7 @@ def draw_food(self, food):
     def draw_score(self, score):
         self.font = pygame.font.Font(None, 25)
         score_display = self.font.render(f"Score: {score}", True, RgbColors.WHITE)
-        self.window.blit(score_display, [0, 0])  # score in top left window corner
+        self.window.blit(score_display, [0, 0])
 
     def render_game_over(self):
         self.font = pygame.font.Font(None, 48)

projects/Snake Game/src/game.py

@@ -7,6 +7,7 @@
 
 
 class Game:
+    """Manages the gameplay logic and its user interactions."""
     def __init__(self):
         self.display = Display()
         self.snake = Snake()
@@ -33,6 +34,11 @@ def game_loop(self):
         pygame.quit()
 
     def is_collision(self):
+        """Checks if the snake has collided with the boundary or with itself.
+
+        Returns:
+            bool: True if a collision is detected, False otherwise.
+        """
         # Snake hits boundary
         if (
                 self.snake.head.x > self.display.width - self.snake.block_size
@@ -65,6 +71,7 @@ def get_user_input(self):
                     self.snake.direction = Direction.DOWN
 
     def play_step(self):
+        """Executes one step through the game."""
         self.get_user_input()
         self.snake.move(self.snake.direction)
         if self.snake.head == self.food:
@@ -79,6 +86,7 @@ def play_step(self):
         return game_over, self.score
 
     def place_food(self):
+        """Randomly places the food on the screen."""
         x = random.randint(0, (
                 self.display.width - GameSettings.BLOCK_SIZE) // GameSettings.BLOCK_SIZE) * GameSettings.BLOCK_SIZE
         y = random.randint(0, (
@@ -88,6 +96,7 @@ def place_food(self):
             self.place_food()
 
     def play_again(self):
+        """Asks the user to play again or quit the game."""
         while True:
             for event in pygame.event.get():
                 if event.type == pygame.QUIT:
@@ -99,12 +108,14 @@ def play_again(self):
                         return True
 
     def restart_game(self):
+        """Resets the state of the game."""
         self.snake = Snake()
         self.score = 0
         self.place_food()
         self.high_score = self.load_high_score()
 
     def load_high_score(self):
+        """Loads the high score from a JSON file."""
         try:
             with open('high_score.json', 'r') as file:
                 data = json.load(file)
@@ -113,6 +124,7 @@ def load_high_score(self):
             return 0
 
     def update_high_score(self, new_score):
+        """Updates the high score in the JSON file if the new score is greater than the current high score."""
         high_score = self.load_high_score()
         if new_score > high_score:
             data = {"high_score": new_score}

projects/Snake Game/src/snake.py

@@ -2,14 +2,28 @@
 
 
 class Snake:
+    """Represents the snake in the game."""
     def __init__(self, init_length=3):
+        """Initializes the snake.
+
+        Args:
+            init_length (int): Length of the snake on initialization.
+        """
         self.head = Point(GameSettings.WIDTH / 2, GameSettings.HEIGHT / 2)
         self.block_size = GameSettings.BLOCK_SIZE
         self.blocks = ([self.head] +
                        [Point(self.head.x - (i * self.block_size), self.head.y) for i in range(1, init_length)])
         self.direction = Direction.RIGHT
 
     def move(self, direction):
+        """Moves the snake in the given direction.
+
+        Args:
+            direction (Direction): The direction to move the snake.
+
+        Returns:
+            Point: The new snake head position.
+        """
         x, y = self.head
         if direction == Direction.RIGHT:
             x += self.block_size
@@ -24,6 +38,11 @@ def move(self, direction):
         return self.head
 
     def self_collision(self):
+        """Checks if the snake collides with itself.
+
+        Returns:
+            bool: True if the snake collides with its body, False otherwise.
+        """
         if self.head in self.blocks[1:]:
             return True
         return False