doc-comments
This skill establishes documentation standards for Biome developers writing comments and rustdoc in the codebase. It distinguishes three comment types—module docs for explanation, item docs for reference, and inline comments for rationale—and teaches which patterns to avoid. The core principle: write for future contributors with no access to your current context, stating how code works rather than how it came to be.
doc-comments teaches Biome contributors how to write effective inline comments, rustdoc, and module documentation for the codebase.
AI-generated summary based on this skill's SKILL.md
Install
biomejs/biome/doc-comments · repository language: Rust
git clone https://github.com/biomejs/biome
cp -r biome/.claude/skills/doc-comments ~/.claude/skills/doc-commentsnpx skillfed install biomejs/biome/doc-commentsFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to write comments in Biome Rust code?
Biome's doc-comments skill establishes three distinct comment types for contributors. Use //! for module-level documentation explaining what a module does and how to use it. Use /// for item documentation (functions, structs, traits) providing reference material about behavior and parameters. Use // for inline comments explaining the rationale behind non-obvious code decisions. The core principle: write for future contributors who lack your current context, focusing on how code works rather than how it came to be.
What's the difference between module docs and item docs in Biome?
Biome's doc-comments distinguishes module docs from item docs by scope and purpose. Module docs use //! at the file's top to explain what the entire module does, its organization, and how to use it—these are explanatory. Item docs use /// on functions, structs, and traits to document their specific behavior, parameters, and return values—these are reference material. Both are rustdoc comments that generate documentation; inline comments (using //) serve a different purpose for rationale.
What comment conventions should Biome developers follow?
Biome's doc-comments skill teaches that contributors must avoid banned comment patterns, which typically include TODO/FIXME markers without context, commented-out code blocks, and vague explanations. Instead, write clear rationale comments explaining why code exists as it does. Use region comments (// region Name / // endregion) to organize long Rust files into logical sections. Apply documentation best practices consistently: be specific, avoid redundancy with code, and assume readers have no access to your development context or commit history.
How should I document functions in Biome codebase?
Biome's doc-comments recommends using /// item docs for all public functions. Start with a one-line summary of what the function does, then add detailed explanation if needed. Document parameters using the `param_name` format and return values clearly. Include examples in doc comments when behavior is non-obvious. For internal functions, decide based on complexity: simple helpers may need only inline rationale comments, while complex logic deserves full item documentation so future maintainers understand intent.
What patterns should I avoid when writing Biome comments?
Biome's doc-comments skill identifies banned comment patterns to avoid: don't leave TODO/FIXME comments without actionable context, don't commit blocks of commented-out code, and don't write comments that merely repeat what the code obviously does. Avoid vague rationale like 'this is needed' without explaining why. Don't use comments to document version history or personal notes. Instead, focus comments on non-obvious decisions, edge cases, and the reasoning behind implementation choices that future contributors need to understand.
How do region comments help organize Biome Rust files?
Biome's doc-comments teaches that region comments organize long Rust files into logical sections using // region Name and // endregion markers. This improves readability by grouping related functions, trait implementations, or helper methods together. Regions help contributors navigate large files quickly and understand code structure at a glance. Use descriptive region names that reflect the section's purpose, making it easier for future maintainers to locate functionality without scrolling through hundreds of lines.
SKILL.md
rendered from the published skill — quoted content, verbatim
Purpose
Comments and doc comments in this repository are read by contributors, months or years after they were written, with none of the context you have right now. This skill defines who that reader is, what each kind of comment is for, and which patterns are banned.
Scope boundary: rustdoc inside declare_lint_rule! / declare_assist_rule!
blocks is end-user documentation — it is generated into the website. This skill
does not apply there; see lint-rule-development.
The Reader
Write for a Biome contributor who is competent in Rust but has no access to your current context: not this conversation, not the pull request, not the issue, not the diff. They see only the
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
.claude/skills/doc-comments/SKILL.md