Repository navigation
emrg: a docstring that cites a section title must cite one the module carries #2455
Description
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 (
ScopeagainstScope, 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