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
Decision gist · record as of 2026-07-27
doc-comments teaches Biome contributors how to write effective inline comments, rustdoc, and module documentation for the codebase. 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.
Use it when
- Biome's doc-comments distinguishes module docs from item docs by scope and purpose.
- Biome's doc-comments skill teaches that contributors must avoid banned comment patterns.
Verify before relying
Read SKILL.md below before installing (1 file). Open directory: indexed for reading, not audited.
Install
biomejs/biome/doc-comments · repository language: Rust
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently 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)
File tree — 1 file
.claude/skills/doc-comments/SKILL.md
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Learn how to write comments and rustdoc for Biome codebase contributions”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
This skill guides you through building new lint rules and assist actions for Biome. It covers rule scaffolding across multiple languages, implementation patterns with semantic analysis, code action setup, and the three-pillar diagnostic framework required for all rules. Use it when adding custom rules like noVar or useConst to Biome's codebase.
This skill guides developers working on Biome's codebase through essential patterns and pitfalls. It covers AST and syntax node navigation, efficient string extraction without allocation, and handling embedded languages across frameworks like Vue and Svelte. Use it to write cleaner, more maintainable code and avoid costly mistakes when extending Biome's parser, analyzer, and formatter.
This skill teaches you how to work with Biome's type inference engine and module graph architecture for building type-aware lint rules. It covers the three-phase type resolution process—local inference, module-level resolution, and cross-module full inference—plus the TypeReference pattern that prevents stale data in an IDE environment. Use it when implementing new type-aware rules, understanding type resolution, or working on type inference features.
Build effective error messages, warnings, and hints for Biome lint rules using the Diagnostic trait and advice system. Learn to craft messages that explain what went wrong, why it matters, and how to fix it—with rich markup, code frames, and actionable guidance.
This skill walks you through the pull request workflow for the Biome project, covering branch selection based on change type, conventional commit title formatting, and the required PR template structure. It ensures you disclose any AI assistance used and prepare your code for review with the right context and test documentation.
This skill guides you through building option migrators for the `biome migrate eslint` command, preserving ESLint rule configurations beyond severity alone. Learn to model ESLint options in Rust, convert them to Biome equivalents, wire typed rule variants into the migration pipeline, and test through fixture-driven specs.
More skills formatter-development (Apache-2.0) · parser-development (Apache-2.0) · testing-codegen (Apache-2.0) · biome (MIT) · jsdoc-typescript-docs (MIT) · Dotnet Xml Docs (unlicensed)