docs(checker): a fence suspends the run, and only a runnable fence is exempt
Two surprises reported by agents in the same hour, neither a behaviour change. A fence SUSPENDS the count rather than ending the run, so two prose lines above a fence and two below is a run of four. That is deliberate -- a reader meets it as one uninterrupted block -- but an agent capped a file to what looked like 2 and 2 and the checker correctly called it 5. And rustdoc does not execute ```text, ```ignore or ```no_run. Two of the six fences in this tree were ```text, so they were claiming the doctest exemption for prose. Only a runnable fence earns it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -6,8 +6,17 @@ A comment run is at most two lines, optionally naming a context/ file for the
|
||||
rest. See context/code/ for where the prose went, and improvise-9c8c for why.
|
||||
|
||||
Counts `///`, `//!` and `//` alike. Attributes are not comments and are
|
||||
ignored. A ``` fence inside a doc comment suspends the count, because a
|
||||
doctest is a running test rather than prose -- see --list-doctests.
|
||||
ignored.
|
||||
|
||||
A ``` fence SUSPENDS the count rather than ending the run: the fenced body is
|
||||
exempt (a doctest is a running test, not prose) but the prose on either side
|
||||
belongs to ONE run and is summed. Two lines above a fence and two below is a
|
||||
run of four, which is over the limit -- and that is deliberate, because a
|
||||
reader meets it as one uninterrupted comment block. See --list-doctests.
|
||||
|
||||
Note rustdoc executes a bare ``` or ```rust fence and does NOT execute
|
||||
```text, ```ignore or ```no_run. Only a runnable fence earns the exemption;
|
||||
the rest is prose wearing a fence and the cap applies to it.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
|
||||
Reference in New Issue
Block a user