You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
emrg: a docstring that cites a section title must cite one the module carries #2455
A docstring that points at a section title must point at one the module carries
What happens today
scripts/feishu-gate.py has a module docstring organised in titled sections, each title
underlined by a row of dashes. The section about what happens to an approval is titled Spent before it is sent.
The OutcomeUnknown class's docstring (same file) tells the reader where to look:
It is its own class because the caller's next move differs from the one a plain Refusal
allows — see "One approval, one message, spent before it is sent" in this module's docstring.
No section carries that title, and none ever has. A reader who follows the citation searches the
module docstring for a heading that is not there, and the sentence it was sent for — the reason the
class exists — is the one thing the pointer was supposed to save them from re-deriving.
The same file has a second citation of the same shape that does resolve
(See "Spent before it is sent" in the module docstring), and scripts/check-doc-count.py has a
third (See "Scope" in the module docstring, where the section title is Scope, stated with its measurement). So the convention is real and mostly honoured; the defect is that nothing checks it,
which is why one site drifted.
What is expected
A citation of the form see "<title>" in [this ]module's docstring names something the reader can
find. Where the citation does not resolve, the two are reconciled — the citation follows the
section's real title, or the section is retitled — and the choice is stated in the change.
What the fix must satisfy
Every citation of that shape resolves against a section title the module's own docstring carries.
None is left pointing at a title that does not exist.
The rule is mechanised, not restated in prose: a guard reads the citations out of the source
and checks them against the module docstring's own titles, so the next drift is caught rather than
discovered.
The subject is discovered, not listed: the titles are the lines a docstring itself underlines,
and the citations are found by pattern. A hand-written list of files or titles admits every
position it omits, and the class this defect belongs to is not confined to the files that carry it
today.
The guard is shown to fail on the defect as it exists now and to pass once it is corrected —
an arm that reports the pre-change tree green has measured nothing.
A citation that matches an underlined title only in part (Scope against Scope, stated with its measurement) counts as resolving: the reader is being sent to a section, and a section found by
its opening words is found. A citation that matches no title at all is the defect.
Activity
argszero commentedon Oct 21, 2026
Handled by #2456