Doc Comments

Writing Contributor Documentation

Write documentation for a human reader, not as a translation of the implementation.

• Start with a plain-language description of what the function returns or accomplishes.
• Use short or medium-length sentences. Keep one main idea per sentence.
• Avoid internal jargon. If a technical term is necessary, explain what it means in the same paragraph.
• Describe business-logic caveats that can surprise callers. Examples include fallback behavior, work limits, ambiguous results, overload ordering, and conditions that return None, Unknown, or an indeterminate result.
• Do not describe implementation details unless callers need them to understand the behavior.

Add an example when the signature cannot clearly show a relationship such as overload selection, argument mapping, import traversal, fallback behavior, or an otherwise ambiguous result. Introduce what the example demonstrates and its expected result. Keep it minimal and self-contained.

Module docs should describe a durable concept or design reason, not list items that will become stale. If there is no durable concept to explain, use a brief one-line description.

Banned Patterns

Narrating the next line. Delete these on sight:

// Increment the generation counter
generation += 1;

Change-history narration. Rewrite as present-tense rationale:

// BAD: We now intern types instead of cloning them.
// GOOD: Interning avoids cloning these types on every lookup.

Reviewer-addressed justification. Move the argument to the pull request:

// BAD: This correctly handles the overload case from the bug report.
// GOOD: Overloads are matched by arity before parameter types, so a
//       partial-arity call cannot select the wrong candidate.

Restated contributor rustdoc. A doc comment that only rewords the item name adds nothing for a contributor:

// BAD:
/// Handles type inference.
fn infer_types(...)

// GOOD:
/// Infers the type of `expr` in `module`, returning `TypeData::Unknown`
/// when the expression references an unresolved import.
fn infer_types(...)

A self-contained summary can still be necessary in CLI help or an editor hover.

Implementation language in end-user documentation. Describe public behavior, not its Rust representation:

// BAD:
/// Stores an `Option<IndentStyle>` consumed by the formatter.

// GOOD:
/// Uses tabs or spaces for indentation. Defaults to tabs.

Replace phrases such as "returns Some", "sets this enum variant", or "the struct contains" with the result the user observes.

Vague hedging. Name the cases and reasons or remove the sentence. Avoid "some cases", "various reasons", "handles edge cases", and "etc."

Ad-hoc section banners (// ----- helpers -----, // ==== TYPES ====). Use the region comment pattern below instead.

Region Comments

Long files group related items with paired region markers:

// #region FILE-LEVEL METHODS
...
// #endregion

This is an established convention across the codebase (biome_service, biome_module_graph, biome_rowan, the parsers). The Workspace trait in crates/biome_service/src/workspace.rs uses it to group its methods. Editors fold on these markers; they exist for navigation, not documentation.

• Pair every // #region with // #endregion.
• Name what the group contains. Use a plain label, or anchor the name to a function when the region holds one entry point and its private support code.
• Use regions only when folding helps in a long file, impl, or trait block.
• Never use a region name instead of rustdoc on its items.

Editing Existing Code

• Edit the source comment, not a generated schema, binding, or help snapshot.
• Preserve accurate details. If behavior changes, correct the specific prose instead of replacing it with generic text.
• Match nearby density and terminology only for the same audience and destination.
• Keep the change focused; do not rewrite unrelated comments to impose a voice.

Self-Check Before Finishing

Read only the comments in the diff, without the implementation:

1. Identify the reader and every destination.
2. Make each comment understandable without the conversation, change history, reviewer, issue, or diff. Keep issue links only as supplemental context for constraints or tracked workarounds.
3. Delete contributor comments recoverable from the code.
4. Ensure end-user comments stand alone without Rust, Biome-internal, or advanced target-language knowledge and state the details needed to predict behavior.
5. Check public names, examples, terminology, inclusivity, and grammar.
6. Inspect generated or rendered output when applicable.

Delete redundant contributor comments, but retain descriptions required by a user-facing surface.

References

• Biome philosophy — principles for user communication.
• Diátaxis — explanation, reference, and rationale.
• lint-rule-development — lint and assist documentation requirements.