Improve parser documentation

1 files changed, 30 insertions, 22 deletions

diff --git a/src/parser.py b/src/parser.py
index 69718e5..4836bdf 100644
--- a/src/parser.py
+++ b/src/parser.py
@@ -1,3 +1,32 @@
+"""
+Load .fcard files into dictionaries.
+
+The parser expects .fcard files in the following format:
+
+FRONT
+This is the front of the first card.
+
+BACK
+This is the back of the first card.
+
+FRONT
+This is another card.
+
+Multiple lines on the front are allowed.
+
+BACK
+Multiple lines on the back?
+
+Also allowed.
+
+FRONT
+...
+
+The cards are represented in dictionary entries of the form:
+
+id: (front_text, back_text)
+"""
+
 from pathlib import Path
 from collections import namedtuple
 from enum import Enum
@@ -65,28 +94,7 @@ def _getCards(f: TextIO) -> Iterator[tuple[id, Card]]:
 
 def parse(path: Path) -> dict[int, Card]:
     """
-    Parse a .fcard file and return a list of Card instances.
-
-    The parser expects .fcard files in the following format:
-
-    FRONT
-    This is the front of the first card.
-
-    BACK
-    This is the back of the first card.
-
-    FRONT
-    This is another card.
-
-    Multiple lines on the front are allowed.
-
-    BACK
-    Multiple lines on the back?
-
-    Also allowed.
-
-    FRONT
-    ...
+    Parse a .fcard file and return a dictionary of Card instances indexed by ID.
     """
     if not path.is_file():
         print(f"[Warning] Not a file: {path}")