Merge pull request steam-bell-92#1085 from basantnema31/fix/issue-888-docs

docs: Expand Documentation with Docstrings and Type Hints for Core Functions

Author: steam-bell-92

games/Tic-Tac-Toe/Tic-Tac-Toe.py

@@ -29,20 +29,20 @@ def main():
     clock = pygame.time.Clock()
 
     # ── Fonts ─────────────────────────────────────────────────
-    def sf(size, bold=False):
+    from typing import Optional, Tuple, List, Any
+
+    def sf(size: int, bold: bool = False) -> pygame.font.Font:
+        """Create a sans-serif font."""
         for n in ["Segoe UI", "Helvetica Neue", "Arial", "DejaVu Sans"]:
-            try:
-                return pygame.font.SysFont(n, size, bold=bold)
-            except pygame.error:
-                pass
+            try: return pygame.font.SysFont(n, size, bold=bold)
+            except: pass
         return pygame.font.Font(None, size)
 
-    def mf(size, bold=False):
+    def mf(size: int, bold: bool = False) -> pygame.font.Font:
+        """Create a monospace font."""
         for n in ["Consolas", "Courier New", "DejaVu Sans Mono"]:
-            try:
-                return pygame.font.SysFont(n, size, bold=bold)
-            except pygame.error:
-                pass
+            try: return pygame.font.SysFont(n, size, bold=bold)
+            except: pass
         return pygame.font.Font(None, size)
 
     F_TAG    = sf(14, bold=True)
@@ -67,7 +67,8 @@ def mf(size, bold=False):
     BX    = (W - (3*CELL + 2*GAP)) // 2   # board left edge  = 43
     BY    = 270                             # board top edge
 
-    def cell_rect(i):
+    def cell_rect(i: int) -> pygame.Rect:
+        """Get the rectangle for a given cell index."""
         r, c = divmod(i, 3)
         return pygame.Rect(BX + c*(CELL+GAP), BY + r*(CELL+GAP), CELL, CELL)
 
@@ -85,24 +86,28 @@ def cell_rect(i):
     BTN2   = pygame.Rect((W//2) + 12,      BTN_Y, BW, BH)
 
     # ── Helpers ───────────────────────────────────────────────
-    def rrect(surf, color, rect, r=14, bw=0, bc=None):
+    def rrect(surf: pygame.Surface, color: Tuple[int, int, int], rect: pygame.Rect, r: int = 14, bw: int = 0, bc: Optional[Tuple[int, int, int]] = None) -> None:
+        """Draw a rounded rectangle."""
         pygame.draw.rect(surf, color, rect, border_radius=r)
         if bw and bc:
             pygame.draw.rect(surf, bc, rect, bw, border_radius=r)
 
-    def tc(surf, txt, font, color, cx, cy):
+    def tc(surf: pygame.Surface, txt: str, font: pygame.font.Font, color: Tuple[int, int, int], cx: int, cy: int) -> None:
+        """Draw centered text."""
         s = font.render(txt, True, color)
         surf.blit(s, (cx - s.get_width()//2, cy - s.get_height()//2))
 
-    def check_winner():
+    def check_winner() -> Tuple[Optional[str], Optional[List[int]]]:
+        """Check if there is a winner and return the winner and winning combination."""
         for a,b,c in WINS:
             if board[a] and board[a]==board[b]==board[c]:
                 return board[a], [a,b,c]
         if "" not in board:
             return "D", []
         return None, None
 
-    def play(i):
+    def play(i: int) -> None:
+        """Make a move at the given index."""
         global current, game_over
         if game_over or board[i]: return
         board[i] = current

math/Armstrong-Number/Armstrong-Number.py

@@ -9,6 +9,7 @@
 from utils.validation import get_int
 
 def is_armstrong_number(n: int) -> bool:
+    """Check if a number is an Armstrong number."""
     if n < 0:
         return False
     num_str = str(n)
@@ -17,6 +18,7 @@ def is_armstrong_number(n: int) -> bool:
     return total == n
 
 def main() -> None:
+    """Run the Armstrong number checker CLI."""
     print("=" * 50)
     print("🔢 ARMSTRONG NUMBER CHECKER 🔢")
     print("=" * 50)

math/Collatz-Conjecture/Collatz-Conjecture.py

@@ -11,19 +11,24 @@
 steps_cache = {1: 0}
 
 
-def collatz_next(n):
+from typing import List, Generator
+
+def collatz_next(n: int) -> int:
+    """Calculate the next number in the Collatz sequence."""
     return n // 2 if n % 2 == 0 else 3 * n + 1
 
 
-def get_remaining_sequence(n):
+def get_remaining_sequence(n: int) -> List[int]:
+    """Calculate the remaining sequence for a given number until it reaches 1."""
     seq = []
     while n != 1:
         n = collatz_next(n)
         seq.append(n)
     return seq
 
 
-def collatz_sequence(start):
+def collatz_sequence(start: int) -> Generator[int, None, None]:
+    """Generate the Collatz sequence starting from the given number."""
     if start in steps_cache:
         n = start
         yield n