---
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]].