fix(gc): a doc comment on a macro invocation fails -D warnings

[proggeramlug]

Closes #8176.

Both legs of rustc-warnings — Warnings (product) and Warnings (host-compatible) — have been red on main and every PR:

error: unused doc comment
error: could not compile `perry-runtime` (lib) due to 1 previous error

Cause

A /// block directly above a crate::perry_thread_local! invocation at crates/perry-runtime/src/gc/roots/stack_maps.rs:209. rustdoc discards a doc comment attached to a macro invocation, so rustc emits unused_doc_comments. That is cosmetic in every other job and fatal in this one, which runs RUSTFLAGS: -D warnings.

It arrived with #8084's #7803 native-slot verifier.

The fix

// instead of ///. The text explains why the verifier exists and is worth keeping, so it stays as a plain comment with a line recording why it cannot be a doc comment — otherwise the next person restores /// and re-breaks the gate.

Verified both directions

$ RUSTFLAGS="-D warnings" cargo check -p perry-runtime --lib     # on main
error: unused doc comment ... exit 101

$ RUSTFLAGS="-D warnings" cargo check -p perry-runtime --lib     # on this branch
exit 0, zero warnings

cargo fmt --all -- --check clean.

Note on why this sat for a day

I saw this warning while validating #8084 and recorded it as pre-existing on the strength of it appearing in an unrelated build log. It was not pre-existing — it came in with that PR, and I merged it. The gate that would have caught it is the one it broke.

Summary by CodeRabbit

• Bug Fixes

  • Fixed compiler warnings caused by documentation comments placed above macro invocations.
  • Preserved the existing diagnostic guidance while ensuring warning-free builds.

• Documentation

  • Added a changelog entry describing the warning fix.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 34e08a75-929a-40ce-b65e-a719a7a28580

📥 Commits

Reviewing files that changed from the base of the PR and between a3118cf and 764dce5.

📒 Files selected for processing (2)

• changelog.d/8176-unused-doc-comment.md
• crates/perry-runtime/src/gc/roots/stack_maps.rs

---

📝 Walkthrough

Walkthrough

The change converts an unused /// comment above a macro invocation in stack_maps.rs to plain // comments. It preserves the diagnostic text and adds a changelog entry describing the warnings-as-errors fix.

Changes

Rust warning fix

Layer / File(s)	Summary
Convert unused documentation comment crates/perry-runtime/src/gc/roots/stack_maps.rs, changelog.d/8176-unused-doc-comment.md	The verifier description now uses plain comments, preventing the unused doc comment warning. The changelog records the fix and its -D warnings impact.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: ⚪ Minimal · up to 764dc

The PR replaces an invalid documentation comment with a regular comment, eliminating the warnings-as-errors build failure without changing runtime behavior. No actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the unused doc comment on a macro invocation and the resulting -D warnings failure.
Description check	✅ Passed	The description explains the cause, fix, related issue, verification commands, and formatting result, with only optional template sections omitted.
Linked Issues check	✅ Passed	The change satisfies issue #8176 by converting the discarded doc comment to a plain comment while preserving the verifier explanation.
Out of Scope Changes check	✅ Passed	All changes are limited to the documented warning fix and its changelog entry; no unrelated code changes are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/8176-unused-doc-comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}