Skip to content

Add container/member doc-comment guideline to AGENTS.md #15285

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
acarl005 merged 1 commit into from
Aug 18, 2026
Merged

Add container/member doc-comment guideline to AGENTS.md #15285

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,12 @@ for itself.
declaration if necessary, but do not repeat that where the const is *referenced*. Another
example is function call sites. Function doc comments explain what they do. Do not repeat
the explanation at the call site.
- **Container docs describe the whole, member docs describe the parts**: A field's, variant's,
or parameter's own doc comment is where that member gets explained. A container's item-level
doc comment (struct, enum, trait) describes the item as a whole and must not enumerate or
re-explain its members. Do not name members in the container's doc comment just to describe
them, and do not restate in a member's doc comment what the container's doc comment already
said. Behavior genuinely shared by several members belongs in exactly one place, not both.
- **Don't enumerate function call sites in doc comments**: Function doc comments should
document their behavior and NOT their callers, e.g. it should never say things like,
"this is used by [certain callers]" or "this is used when...".
Expand Down
Loading