dazuma
## What happens When an object's docstring comes from an `.rbs` signature file, RBS's own `<!-- rdoc-file=... -->` provenance marker is carried into the docstring verbatim and rendered as content. Because the marker sits at the very front of the docstring, it also becomes the leading text of the extracted summary — so it lands in the `description:` frontmatter, in the `index.md` bullet, and in the parent's `## Member Summary` bullet, which are exactly the discovery surfaces an agent reads first. ## Repro Build a bundle for a gem that ships `.rbs` sigs with imported core docs: ``` toys agentdocs gems base64:0.3.0 ``` `base64-0.3.0/Base64.md`: ```markdown --- type: Ruby Module title: Base64 description: "<!-- rdoc-file=lib/base64.rb --> Module Base64 provides methods for: ..." --- # module Base64 - **Defined in:** `lib/base64.rb`, `sig/base64.rbs` <!-- rdoc-file=lib/base64.rb --> Module Base64 provides methods for: ... ``` `base64-0.3.0/index.md`: ```markdown * [`Base64`](Base64.md) - <!-- rdoc-file=lib/base64.rb --> Module Base64 provides methods for: ... ``` ## Source of the marker It is upstream content, not something the template introduces — `base64-0.3.0/sig/base64.rbs` begins: ``` # <!-- rdoc-file=lib/base64.rb --> # Module Base64 provides methods for: ``` RBS emits these markers when importing core/stdlib RDoc into signature files. They are invisible in HTML output, which is presumably why nobody upstream has noticed, but this format is read as plain text. ## Marker forms RBS emits two. Across every `.rbs` file installed locally (467 files carrying markers, 14,525 marker-bearing comment blocks), **every single marker leads its comment block — none appears mid-docstring.** **Form A** — 4,879 occurrences, one line: ``` <!-- rdoc-file=lib/base64.rb --> ``` **Form B** — 9,682 occurrences, roughly twice as common, carrying up to 8 RDoc call-seq lines: ``` <!-- rdoc-file=lib/prime.rb - each(ubound = nil, generator = EratosthenesGenerator.new, &block) --> ``` ## Scope Two of 117 bundles in a local `agentdocs gems --all-latest` run are affected: - **`base64-0.3.0`** — Form A, module-level. Cosmetic noise in the body, the `description:` frontmatter, and the `index.md` entry. - **`prime-0.1.4`** — Form B, method-level, and worse. `RDoc::Markup::ToMarkdown` renders the marker's inner lines 4-space-indented, so `Prime.md` gets a stray **indented code block**, not just noise — a structural corruption. It also leaks into four `**Class Methods**` summary bullets (`Prime.md:77-88`), a surface the original report didn't cover. So it is rare today, but it is not purely cosmetic, and it tracks how widely gems ship doc-carrying `.rbs` files. The `rbs` gem alone ships 7,285 markers in `core/` and `stdlib/` — outside YARD's `sig/**/*.rbs` default glob today, and one vendoring convention away from being in scope. ## Disposition Designed 2026-09-14; see "RBS provenance markers in `.rbs`-sourced docstrings" under "Decisions" in `docs/dev/DESIGN.md` for the decision and the rejected alternatives. This issue records the defect; the design doc owns the fix. Per the project workflow, implementation goes through a hand-authored `examples/` fixture and human review first.