Improve documentation

1 files changed, 36 insertions, 5 deletions

diff --git a/src/scheduler.py b/src/scheduler.py
index 575ec9d..e1c783b 100644
--- a/src/scheduler.py
+++ b/src/scheduler.py
@@ -3,24 +3,55 @@ from abc import abstractmethod
 from card import Card
 
 class Scheduler(Protocol):
+    """
+    Schedulers must implement this interface to be usable in a session.
+    """
     @abstractmethod
-    def __init__(self, cards: dict[str, Card], state: dict): raise NotImplementedError
+    def __init__(self, cards: dict[str, Card], state: dict):
+        """
+        Create a new instance of the scheduler from a dictionary of
+        Cards indexed by ID and a scheduler-specific state as a dict.
+        """
+        raise NotImplementedError
 
     @abstractmethod
-    def practice(self, size: int) -> list[str]: raise NotImplementedError
+    def practice(self, size: int) -> list[str]:
+        """
+        Return a list of card IDs of the requested size, if possible.
+        This list is intended for practice.
+        """
+        raise NotImplementedError
 
     @abstractmethod
-    def test(self, size: int) -> list[str]: raise NotImplementedError
+    def test(self, size: int) -> list[str]:
+        """
+        Return a list of card IDs of the requested size, if possible.
+        This list is intended to test the player's knowledge.
+        """
+        raise NotImplementedError
 
     @abstractmethod
-    def update(self, results: dict[str, int]) -> None: raise NotImplementedError
+    def update(self, results: dict[str, int]) -> None:
+        """
+        Takes a dictionary of card IDs and integers, where the integer
+        is 0 if the player failed to guess the other side of the card,
+        of 1 if the player succeeded.
+        """
+        raise NotImplementedError
 
     @abstractmethod
-    def getState(self) -> dict: raise NotImplementedError
+    def getState(self) -> dict:
+        """
+        Return the scheduler's state for storage.
+        """
+        raise NotImplementedError
 
 SCHEDULERS = ["brutal"]
 
 def getSchedulerClass(name: str) -> Scheduler:
+    """
+    Returns the class object for the requested scheduler, if one exists.
+    """
     match name:
         case "brutal":
             from scheduler_brutal import SchedulerBrutal