docs: Expand Documentation with Docstrings and Type Hints for Core Functions (Fixes steam-bell-92#888)

Author: basantnema31

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

@@ -27,13 +27,17 @@
 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: 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: pass
@@ -61,7 +65,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)
 
@@ -79,24 +84,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
@@ -108,11 +117,13 @@ def play(i):
     else:
         current = "O" if current == "X" else "X"
 
-def new_game():
+def new_game() -> None:
+    """Start a new game."""
     global board, current, game_over
     board = [""] * 9; current = "X"; game_over = False
 
-def reset_all():
+def reset_all() -> None:
+    """Reset the game scores and start a new game."""
     scores["X"] = scores["O"] = scores["D"] = 0
     new_game()
 

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