{"enrichment":{"faq":[{"a":"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.","q":"How to write comments in Biome Rust code?"},{"a":"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\u2014these are explanatory. Item docs use /// on functions, structs, and traits to document their specific behavior, parameters, and return values\u2014these are reference material. Both are rustdoc comments that generate documentation; inline comments (using //) serve a different purpose for rationale.","q":"What's the difference between module docs and item docs in Biome?"},{"a":"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.","q":"What comment conventions should Biome developers follow?"},{"a":"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.","q":"How should I document functions in Biome codebase?"},{"a":"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.","q":"What patterns should I avoid when writing Biome comments?"},{"a":"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.","q":"How do region comments help organize Biome Rust files?"}],"shadow_tags":["developer-documentation","code-style-guide","rust-conventions","contributor-onboarding","documentation-patterns","comment-hygiene","codebase-standards","technical-writing","maintainability-practices"],"summary_rewrite":"This skill establishes documentation standards for Biome developers writing comments and rustdoc in the codebase. It distinguishes three comment types\u2014module docs for explanation, item docs for reference, and inline comments for rationale\u2014and 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."},"files":[{"bytes":8759,"path":".claude/skills/doc-comments/SKILL.md","sha256":"d1f63dfdbe11ff3405b1aec5ad8ee28a085bc35cad02987c58a49c97aa850c09","url":"https://skillfed.io/files/biomejs/biome/doc-comments/5a539edb/SKILL.md"}],"id":"biomejs/biome/doc-comments","links":{"html":"https://skillfed.io/biomejs/biome/doc-comments","md":"https://skillfed.io/biomejs/biome/doc-comments.md","repo":"https://github.com/biomejs/biome"},"meta":{"agents_supported":["claude-code"],"first_seen":"2026-07-28","forks":1157,"language":"Rust","last_updated":"2026-07-27","license":"Apache-2.0","name":"doc-comments","publisher":"biomejs","stars":25418},"relations":{"similar":[{"id":"biomejs/biome/lint-rule-development"},{"id":"biomejs/biome/biome-developer"},{"id":"biomejs/biome/type-inference"},{"id":"biomejs/biome/diagnostics-development"},{"id":"biomejs/biome/pull-request"},{"id":"biomejs/biome/eslint-migrate-options"},{"id":"biomejs/biome/formatter-development"},{"id":"biomejs/biome/parser-development"},{"id":"biomejs/biome/testing-codegen"},{"id":"bobmatnyc/claude-mpm-skills/biome"}]},"slug":{"owner":"biomejs","repo":"biome","skill":"doc-comments"},"version":"5a539edb"}