refactor: Add docstrings to pod methods and rename pod sorting functions for improved clarity and semantic meaning.

Author: eVen-gits

src/core.py

@@ -2698,6 +2698,9 @@ def auto_auto_assign_seats(self):
 
     def reorder_players(self, order: list[int]) -> None:
         """Reorders the players in the pod.
+        Passing range(len(self._players)) will result no change in the order.
+        Passing [0, 1, 2, 3] will result no change in the order.
+        Passing [3, 2, 1, 0] will reverse the order of the players.
 
         Args:
             order: A list of integers representing the new order of the players.
@@ -2712,13 +2715,19 @@ def reorder_players(self, order: list[int]) -> None:
         self._players[:] = np.take(self._players, order)
 
     def clear(self):
+        """Clears the pod of all players.
+        This method is called by the round when the pod is removed.
+        """
         players = [p for p in self.players]
         for p in players:
             self.remove_player(p, cleanup=False)
         # self.players.clear()
 
     @property
     def name(self):
+        """Returns the name of the pod.
+        The name of the pod is "Pod {}".format(self.table).
+        """
         return "Pod {}".format(self.table)
 
     @override
@@ -3171,11 +3180,9 @@ def create_pairings(self) -> None:
                 pod.auto_auto_assign_seats()
 
         self.sort_pods()
-        self.apply_table_preference()
-
-    def sort_pods(self) -> None:
-        """Sort pods by number of players and average rating."""
 
+    def sort_pods_by_power(self) -> None:
+        """Sort pods by number of players and average rating to establish a power-level baseline."""
         pods_sorted = sorted(
             self.pods,
             key=lambda x: (
@@ -3186,15 +3193,17 @@ def sort_pods(self) -> None:
         )
         self._pods[:] = [pod.uid for pod in pods_sorted]
 
-    def apply_table_preference(self) -> bool:
+    def sort_pods(self) -> bool:
         """Try to apply table preferences for players. Pod index is table number.
         Preserves the relative power-sorted order of non-locked pods.
         Prioritizes maximizing the number of satisfied preferences.
 
         Returns:
             bool: True if table preferences were applied, False otherwise.
         """
-        pods = self.pods  # Already sorted by power
+        self.sort_pods_by_power()
+
+        pods = self.pods  # Expect pods to be already sorted by power
         n = len(pods)
         if n == 0:
             return False