Docstrings: crawl exploration - #87
Merged
Merged
Conversation
Rewrite the module docstring and the eleven exported members of osrlib.crawl.exploration for a reader working from the published API reference alone: where the module sits between the command models, the session that dispatches them, and the events they emit; what each member is for; what to call instead; and a runnable example on every function and mapping. Claude-Session: https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa
Say that an exploration rate of 0 also covers a party with no living member, and that _handle_move_party rejects with reason `overloaded` either way. Name Character.movement_rate as what to call for one character's allowance. Say in the module docstring that DropItems and UseItem also serve encounter mode. Say that adding a key to HEALING_SERVICES adds no service, because PurchaseHealing.service rejects a name that isn't already on it. Claude-Session: https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa
Bring the internal docstrings and the code comments into the same register as the public ones. Em and en dashes go, semicolon splices become two sentences, and "pinned" gives way to the fact each comment was compressing: what osrlib fixes where the rules leave a choice, and which of those the adaptations register records. Checked each reworded claim against the code, and the module's executable statements are byte-identical to origin/main. Claude-Session: https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa
This was referenced Sep 14, 2026
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 module docstring and the eleven exported members of
osrlib.crawl.explorationso a reader on the published reference can work from that page alone. The module docstring now leads with where the module sits: which command models inosrlib.crawl.commandsit answers, thatGameSession.executeis the entry point andHANDLERSthe lookup it uses, and that what comes back is aCommandResultof rejections orosrlib.crawl.eventsmodels. It then names the per-turn bookkeeping the session runs on its own cadence, and closes with a usage block that enters a dungeon, moves, gets a move rejected, and reads the exploration rate.The four effect-kind constants,
EXHAUSTED_DEFINITION,HANDLERSandHEALING_SERVICEShad no docstrings and rendered as bare names. They now say what each is for, how to query it, and what to use instead: the kind constants go throughEffectsLedger.active_on,HANDLERSsays to send commands throughexecuterather than calling a handler out of the mapping, andHEALING_SERVICESsays its keys are exactly the valuesPurchaseHealing.serviceaccepts. Every function and both mappings carry a runnable example, and all of them ran under the docs harness.I corrected one docstring because the code disagrees with it.
check_fatiguesaid it returns nothing "once fatigue is already active on every living member", but the guard at src/osrlib/crawl/exploration.py:776 short-circuits onany(...), not every member, so the docstring now says the list is empty when any living member is already fatigued. I also replacedwandering_interval's "an effectively unreachable value outside a dungeon" with the number the function actually returns, 1000000000, since a caller comparing against it needs to know what it is.No examples are
no-run, and I left nothing in__all__undocumented. The underscore-prefixed handlers stay undocumented: the renderer filters them out, and the members that would send a reader to one name the command class instead.https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa