Docstrings: crawl hooks and views - #98
Merged
Merged
Conversation
Rewrite the docstrings of gates, triggers, quests, narrative, the interpreter, and views for a developer reading the published reference. Each module docstring now opens with where the thing sits: the authoring model that holds it, the part of the session that evaluates it, and the events that report the result. Every pydantic field gets a PEP 224 attribute docstring so the reference renders prose instead of a bare name, and the runnable examples were all run against the code. Correct two claims in the interpreter that disagreed with the code: the cascade bound suppresses issuing, not matching, and the walk keeps evaluating clauses past the bound. Claude-Session: https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa
The views module docstring said neither builder reads the event log; the referee view is the save's serialization and includes it, so the sentence now separates the two. The player-view exclusion list gains the quests that are not active, since the projection keeps only active ones. RefereeView.state now links the function that names every save key. The interpreter docstring now says that past the cascade bound a quest the event would have activated records one note and stops, so its objective clauses are not evaluated, and that a quest walk returns at the completion it issues, leaving a second objective that matched the same event for the next event. QuestSpec.completion says the same for the author. NarrativeBlock.guidance now says osrlib reads it nowhere and a narrator takes it from the authored document. Claude-Session: https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
I rewrote the docstrings for the authored hooks (gates, triggers, quests, narrative), the interpreter that plays them, and the view projections, so a developer reading the published reference can wire an adventure and render a front end without opening the source. Each module docstring now opens with placement: which authoring model holds the thing, which part of the session evaluates it, and which events report the result. Every pydantic field in the six files has a PEP 224 attribute docstring, so the field rows render with prose instead of bare names, which also makes
MemberView.idand its siblings resolvable targets for the command docstrings that send readers to the view for ids. The new examples run under the docs harness: the interpreter's builds a session with a trigger, registers the listener, and shows the flag, the fired-mark, and the journal entry the firing produced;build_player_viewandbuild_referee_vieweach build a session and show what the two projections do and do not contain.I corrected two claims in the interpreter that disagreed with the code. The class docstring said "matching stops below depth five" (src/osrlib/crawl/interpreter.py:287 before the change); matching does not stop, since
handleruns_would_fireand_advanceevaluates every clause past the bound, and what stops is issuing. The_MAX_MATCH_DEPTHdocstring had the same error and now says it is the deepest events a firing or a quest advancement still acts on (src/osrlib/crawl/interpreter.py:60).The only
no-runblock is the one-line registration fragment in theInterpreterclass docstring, which names asessionbuilt elsewhere; its runnable twin is the full example in the same docstring. I left nothing undocumented on purpose. I found no code defects.uv run ruff format --check && uv run ruff check && uv run pyright && uv run pytest -q && uv run mkdocs build --strictpasses: 2273 passed, 73 skipped, pyright clean, strict build clean.https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa