Skip to content

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

Merged
acarl005 merged 1 commit into
masterfrom
agents-md-container-member-comments
Aug 18, 2026
Merged

Add container/member doc-comment guideline to AGENTS.md#15285
acarl005 merged 1 commit into
masterfrom
agents-md-container-member-comments

Conversation

@warp-agent-staging

Copy link
Copy Markdown
Contributor

Description

Adds a new guideline to the Comments section of AGENTS.md, based on feedback from a Slack thread: an agent had added a struct-level doc comment that enumerated and explained several of the struct's fields, while those same fields also carried their own doc comments repeating the same explanation (see app/src/terminal/event.rs in PR #15162, the UserBlockCompleted struct).

The new bullet, **Container docs describe the whole, member docs describe the parts**, states that a member's own doc comment is where that member gets explained, and a container's item-level doc comment must not enumerate or re-explain its members. It generalizes the existing **Single-source of documentation** bullet to the container/member relationship, and is placed directly after it to keep related guidance together.

This is a docs-only change to AGENTS.md; no other files are touched.

Testing

This is a Markdown documentation change with no executable code, so no automated or manual testing applies. I confirmed the new bullet's lines stay within the section's documented ~100-column wrap, consistent with the surrounding bullets.

  • I have manually tested my changes locally with ./script/run

Agent Mode

  • Warp Agent Mode - This PR was created via Warp's AI Agent Mode

@warp-agent-staging

Copy link
Copy Markdown
Contributor Author

This PR was generated with Warp.

Comment @warp-factory on this PR to send it follow-up work.

View run View conversation

@acarl005
acarl005 marked this pull request as ready for review August 18, 2026 22:07
@acarl005
acarl005 enabled auto-merge (squash) August 18, 2026 22:08
@acarl005 acarl005 self-assigned this Aug 18, 2026
@acarl005
acarl005 merged commit b90c734 into master Aug 18, 2026
48 checks passed
@acarl005
acarl005 deleted the agents-md-container-member-comments branch August 18, 2026 22:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant