Docstrings: core basics - #96
Merged
Merged
Conversation
Rewrite the docstrings of the kernel's foundation modules so a developer reading the published reference can call them without opening the source: the RNG streams, dice, the game clock, the ruleset flags, ability scores, the SRD lookup tables, alignment, and structured rejections. Every pydantic field, enum member, and module constant now carries its own attribute docstring, every documented function has a runnable example, and osrlib.core's package docstring is the subpackage front page. Claude-Session: https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa
Force door: the session handler sets the noise flag, opens the door and springs its trap on a success, and alerts the area beyond on a failure. It advances no clock, so the time claim is gone. Formation width: the cap is the party's frontage divided by the five feet a combatant needs, at ten feet per cell, so two abreast in a one-cell corridor and four in a room two cells across. The flag defaults on, so the text now describes turning it off. Monster saves and XP bands: the code tests the Hit Dice count and the d4 hit die, not fixed hit points. A hydra takes the band for its count. Turning and ability checks: name the rule instead of calling undead powerful or a task easy, and quote the SRD's own difficulty wording. 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.
A developer reading the reference for
osrlib.core's foundation modules can now call them without opening the source. The RNG streams say how to fork a container from a master seed, which stream to ask for, and what saving and restoring a position does; the dice page gives the grammar, the evaluation order, and the fact that totals aren't clamped; the clock says what an advance returns and who consumes it; everyRulesetflag says what it changes, what its default is, and which family it belongs to; the ability tables give the range of every modifier they return; and the SRD lookup tables say which loader produces them and which function turns a result into play. Every pydantic field, enum member, and module constant carries its own attribute docstring, so the rendered field rows are no longer bare names, and every documented function has an example I ran against the code.Two docstrings disagreed with the code and I corrected them.
src/osrlib/core/clock.py:1said the boundary crossings an advance returns are what lets the effects engine resolve expirations and ticks at each boundary;EffectsLedger.advanceadvances the clock and resolves every round itself, and nothing in the library reads aBoundaryCrossing, so the module now says the crossings are for the caller.src/osrlib/core/abilities.py:666gained a claim in my first draft that a character gets one attempt per stuck door and that the attempt takes a turn;ForceDoorenforces neither, soopen_doors_checknow says it rolls and reports and leaves the time and the noise to you.I left out one claim I could not verify. The SRD's intelligence table prints
BasicbetweenIlliterateandLiteratewithout defining it, soLiteracy.BASICsays it's the middle step at intelligence 6 to 8 rather than what a character at that step can read.One fragment is fenced
no-run: none. Every block runs under the examples harness.The packet asked for the adaptations register to be linked as
[the adaptations register][adaptations-and-pinned-interpretations]. That anchor contains the word the vocabulary gate in the docs gates bans, so the three links use the full site URL instead.https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa