---
name: rust-commenting
description: Add consistent, minimal comments to Rust source files. Use this skill whenever the user asks to comment, document, or annotate Rust code — including requests like "add comments", "document this module", "annotate these structs", or any variation involving Rust files and documentation/comments. Also trigger when the user asks to clean up or standardize existing Rust comments.
disable-model-invocation: false
user-invocable: true
---

# Rust Commenter

This is a style pass, not a logic change. You add consistent, minimal comments to Rust code. Your philosophy is that good code is mostly self-documenting — comments exist to fill genuine gaps in understanding, not to narrate what the code already says.

*Note: This is lighter-weight work — suitable for faster model tiers (e.g., Sonnet).*

## Module-level comments (`//!`)

Every `.rs` file must have a `//!` comment as the very first line — no exceptions. One short line describing what the module is for. Think of it as a signpost, not a README.

```rust
//! Token parsing and validation.
```

```rust
//! HTTP middleware for rate limiting.
```

If the module re-exports or is a thin wrapper, a few words suffice:

```rust
//! Public API surface.
```

Do not use `//!` anywhere else in the file — only at the top.

## Struct and enum comments (`///`)

Add a `///` doc comment above a struct or enum **only when the name and fields don't tell the full story**. If `struct UserConfig` has fields like `theme`, `language`, `timezone` — that's self-evident, skip it. But if there's a non-obvious invariant, lifecycle, or relationship worth knowing, add a single line above the struct.

```rust
/// Tracks in-flight requests to enforce per-client concurrency limits.
pub struct RequestGate {
```

Never add per-field `///` comments on struct fields or enum variants — if the field names aren't self-explanatory, that's a naming problem, not a commenting problem. The only place a struct/enum comment belongs is above the type itself. Same for enums: comment the enum if needed, never the individual variants.

## Function and method comments (`///`)

Same rule: only when the signature doesn't speak for itself. A function called `fn load_config(path: &Path) -> Result<Config>` needs nothing. But if there's a subtle contract — ordering dependency, fallback behavior, side effects — say so in one line.

```rust
/// Returns `None` if the file is missing rather than erroring.
pub fn load() -> Option<Self> {
```

Do not describe parameters or return types that are already clear from the signature. Never add `# Arguments`, `# Returns`, `# Errors`, `# Panics`, or `# Safety` sections — these bloat comments and rarely earn their keep. A single line that captures the key insight is always enough. If a function can error, say so in the one-liner: `/// Loads config from disk, returning an error if the file is missing.` — don't split it into a summary plus a separate `# Errors` block.

## Inline comments

Avoid them. The bar is high: only add an inline comment when the **why** behind a piece of logic is genuinely non-obvious and can't be clarified by renaming or restructuring. If you find yourself wanting to add one, first consider whether a better variable name or a small extraction would eliminate the need.

When you do add one, keep it short — a fragment, not a sentence:

```rust
// prev goes to inactive only if it was a real project
if !prev.id.is_empty() {
```

## What NOT to do

- Don't add per-field comments on structs or per-variant comments on enums — if a comment is needed, it goes above the type itself
- Don't add comments that restate the code: `// increment counter` above `counter += 1`
- Don't add comments to every function — most functions don't need them
- Don't use `/** */` block comments — stick with `//!` for modules and `///` for items
- Don't add license headers or autogenerated boilerplate
- Don't add `// TODO` or `// FIXME` unless the user specifically asks for them
- Don't add rustdoc sections (`# Errors`, `# Panics`, `# Safety`, `# Examples`, `# Arguments`, `# Returns`) — fold the essential info into a single doc line instead
- Don't use multi-line doc comments when one line will do — every `///` block should be as few lines as possible
- Don't touch the code itself — only add or revise comments

## Process

1. Read the target file(s) thoroughly first
2. Understand what each module, struct, and function does
3. Add `//!` to the top of every module file
4. Scan structs/enums — comment only the non-obvious ones
5. Scan functions/methods — comment only where the signature leaves genuine ambiguity
6. Do a final pass: if any comment just restates what the code says, remove it

When in doubt, leave it out. A codebase with too few comments is far better than one cluttered with noise.
