docs: add English docstrings and SLR(1) algorithm comments (T0)

[henrylee97]

Summary

• Add module-level docstrings to all plare/*.py files
• Add class and method docstrings to every public type (Token, Lexer, Parser, Rule, Item, State, action types, etc.)
• Add block comments on the five construction phases in Parser.__init__ and on closure, goto, calc_first, calc_follow, and Parser.parse stating this is SLR(1), the invariants each routine relies on, and the over-approximation that T6 will fix

No logic changes — git diff --stat shows additions in docstrings and comments only.

Checklist

• pytest -q green (8 passed)
• No behavior changes (pure documentation pass)
• No Korean strings remain
• HANDOFF.md T0 marked as DONE

[github-actions]

Super-linter summary

Language	Validation result
PYTHON_BLACK	Fail ❌
PYTHON_ISORT	Pass ✅
YAML	Pass ✅

Super-linter detected linting errors

For more information, see the GitHub Actions workflow run

Powered by Super-linter

PYTHON_BLACK

--- /github/workspace/plare/lexer.py	2026-05-04 08:29:28.521939+00:00
+++ /github/workspace/plare/lexer.py	2026-05-04 08:29:35.727461+00:00
@@ -110,11 +110,11 @@
                     continue
                 matched = match.group(0)
                 logger.debug(
                     "Pattern matched: %s (from %s), %s", regex, var, repr(matched)
                 )
-                src = src[len(matched):]
+                src = src[len(matched) :]
                 match pattern:
                     case str():
                         var = pattern
                     case type():
                         yield pattern(matched, lineno=lineno, offset=offset)would reformat /github/workspace/plare/lexer.py

Oh no! 💥 💔 💥
1 file would be reformatted, 9 files would be left unchanged.

[github-actions]

Super-linter summary

Language	Validation result
PYTHON_BLACK	Fail ❌
PYTHON_ISORT	Pass ✅
YAML	Pass ✅

Super-linter detected linting errors

For more information, see the GitHub Actions workflow run

Powered by Super-linter

PYTHON_BLACK

--- /github/workspace/plare/lexer.py	2026-05-04 08:32:43.442057+00:00
+++ /github/workspace/plare/lexer.py	2026-05-04 08:32:50.225424+00:00
@@ -110,11 +110,11 @@
                     continue
                 matched = match.group(0)
                 logger.debug(
                     "Pattern matched: %s (from %s), %s", regex, var, repr(matched)
                 )
-                src = src[len(matched):]
+                src = src[len(matched) :]
                 match pattern:
                     case str():
                         var = pattern
                     case type():
                         yield pattern(matched, lineno=lineno, offset=offset)would reformat /github/workspace/plare/lexer.py

Oh no! 💥 💔 💥
1 file would be reformatted, 9 files would be left unchanged.

[github-actions]

Super-linter summary

Language	Validation result
PYTHON_BLACK	Fail ❌
PYTHON_ISORT	Pass ✅
YAML	Pass ✅

Super-linter detected linting errors

For more information, see the GitHub Actions workflow run

Powered by Super-linter

PYTHON_BLACK

--- /github/workspace/plare/lexer.py	2026-05-04 08:32:48.064321+00:00
+++ /github/workspace/plare/lexer.py	2026-05-04 08:32:55.197770+00:00
@@ -110,11 +110,11 @@
                     continue
                 matched = match.group(0)
                 logger.debug(
                     "Pattern matched: %s (from %s), %s", regex, var, repr(matched)
                 )
-                src = src[len(matched):]
+                src = src[len(matched) :]
                 match pattern:
                     case str():
                         var = pattern
                     case type():
                         yield pattern(matched, lineno=lineno, offset=offset)would reformat /github/workspace/plare/lexer.py

Oh no! 💥 💔 💥
1 file would be reformatted, 9 files would be left unchanged.

[github-actions]

Pytest Report

Test Results

• Tests: 8
• Errors: 0
• Failures: 0
• Skipped: 0

Comment by ✨sambyeol/publish-pytest-action

[github-actions]

Pytest Report

Test Results

• Tests: 8
• Errors: 0
• Failures: 0
• Skipped: 0

Comment by ✨sambyeol/publish-pytest-action

[github-actions]

Super-linter summary

Language	Validation result
PYTHON_BLACK	Pass ✅
PYTHON_ISORT	Pass ✅
YAML	Pass ✅

All files and directories linted successfully

For more information, see the GitHub Actions workflow run

Powered by Super-linter