---
name: inserting-a-clap-variant-orphans-the-next-doc-comment
description: "Inserting a new clap subcommand variant right above an existing one steals ITS `///` doc block — the new verb ships the old verb's help and the old verb ships none"
metadata: 
  node_type: memory
  type: reference
  originSessionId: f635b37f-9074-4de1-9540-eb96bcd49e42
  modified: 2026-08-22T03:52:14.529Z
---

A clap `///` doc block belongs to whatever variant FOLLOWS it. Inserting a new variant
between an existing doc comment and its variant silently re-parents that help text: the new
verb's `--help` opens with the old verb's prose, and the old verb renders with an EMPTY
summary. Nothing fails to compile, no test covers `--help` prose, and the shipped help is
wrong on two commands at once.

Measured 2026-08-04 (#109): adding `endpoint gc` above `endpoint purge` made the generated
`docs-site/src/cli/reference.md` read `gc  Permanently remove an endpoint and every record
keyed on it` with `purge` blank. **The generated reference is what caught it** — the diff
showed both rows moving.

## THE CLASS IS WIDER THAN CLAP: a `#[test]` insert steals a test's doc block too (todlando, releases#208, 2026-08-22)

Same mechanism, different surface, and this one has NO generated artifact to catch it. Building #208 he inserted a new pin between releases#177's doc block and #177's own `#[test]`, so the doc re-parented onto HIS test and #177's cell was left with none. It compiles, both tests pass, and the only loss is that the cell explaining WHY #177's leg exists now sits above a different cell — which is how a later reader deletes or "relaxes" a guard whose reasoning has quietly moved.

Rust attaches every `///` to the item that FOLLOWS it. That is true of clap variants, `#[test]` fns, struct fields, consts, and impl methods alike — the clap case is just the one with a generated reference to expose it. Everywhere else the evidence is only in the diff.

**How to apply, generalized:** anchor ANY item insertion on the PRECEDING item's closing brace, never on the following item's opening line. After inserting near a documented item, verify the doc still sits with its original owner — for tests, that the cell you did not touch still carries its prose. He caught this by reading his own diff, which is the only instrument that sees it; on the clap surface `xtask gen` also catches it.

**How to apply:** when adding a clap variant, anchor the edit on the PRECEDING variant's
closing `},`, not on the following variant's `Name {` — or, after any enum insertion, run
`xtask.exe gen` and READ the diff for rows other than the one you added. A summary shifting
on a command you did not touch is this bug. Kin [[clap-doc-comment-leaks-req-tag]],
[[xtask-gen-deadlocks-under-cargo-run]], [[cli-command-docs-drift]].

## THIRD FACE, 2026-09-09 (hertz, doyle caught it in review) — TWO `///` BLOCKS WITH NO BLANK LINE BETWEEN THEM ARE ONE BLOCK

Same mechanism, and the one shape the "anchor on the preceding item's closing brace" rule does NOT
catch, because there was no preceding brace to anchor on: I added a new `pub struct Survivor` with
its own doc block into `crates/spt/tests/common/reap.rs` immediately after `Population`'s doc block
and BEFORE `Population` itself. Rust does not see two doc blocks — it sees one run of `///` lines
that binds to the item that follows. So `Survivor` shipped with Population's prose glued on top of
its own, and **`pub struct Population` ended up with NO doc at all**, in a file whose entire value is
the reasoning in its doc blocks.

**Why it survives everything a normal lane runs:** it compiles, `clippy -D warnings` is silent
(nothing is missing a doc where one is required), the test passes, `traceable-reqs` is unaffected,
and the diff LOOKS right — the added lines are all mine and each reads correctly in isolation. Only
the BINDING moved, and nothing in a diff renders a binding. Mine went through four green legs.

**The check that catches it, from doyle, and it is two commands not a habit:** after adding an item
near documented code, read the **two lines immediately above each `pub` item in the region** — the
one you added and the one you added it near. The tell is what sits directly above the original item:
if it is `#[derive(...)]` preceded by prose that is clearly about the OTHER type, the doc has moved.

**The fix is a MOVE, not a rewrite, and it should be byte-conserving:** lift the new item WITH its
own doc block ABOVE the existing doc block, separated by a blank line, so the original block
re-attaches. Assert that: my move went 20,938 bytes -> 20,938 bytes, which is the cheap proof that no
prose was edited while relocating it. A doc-only move needs no rebuild; re-run the requirement check
once and say the tags were unaffected rather than assuming it.

Kin: this file's clap and `#[test]` faces above ([[behavior-change-grep-tests-not-comments]] is the
opposite failure — reading comments as behaviour); the general family is that Rust binds every `///`
to the NEXT item and no green leg has an opinion about which item that is.