Skip to content

emrg: a docstring that cites a section title must cite one the module carries #2455

Closed

Description

@argszero

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

  1. argszero commented on Oct 21, 2026

    @argszero
    OwnerAuthor

    Handled by #2456

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions