home / skills / redisearch / redisearch / rust-docs-guidelines

rust-docs-guidelines skill

safe

This skill helps Rust projects improve documentation quality by applying consistent intra-documentation linking and focusing on explanation of concepts.

npx playbooks add skill redisearch/redisearch --skill rust-docs-guidelines

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

997 B

---
name: rust-docs-guidelines
description: Guidelines for writing Rust documentation
---

# Rust Docs Guidelines

Standards to follow when writing Rust documentation.

## Guidelines

- Key concepts should be explained only once. All other documentation should use an intra-documentation link to the first explanation.
- Always use an intra-documentation link when mentioning a Rust symbol (type, function, constant, etc.).
- Avoid referring to specific lines or line ranges, as they may change over time.
  Use line comments if the documentation needs to be attached to a specific code section inside
  a function/method body.
- Focus on why, not how.
  In particular, avoid explaining trivial implementation details in line comments.
- Refer to constants using intra-documentation links. Don't hard-code their values in the documentation of other items.
- Intra-documentation links to private items are preferable to duplication. Add `#[allow(rustdoc::private_intra_doc_links)]` where relevant.

Overview

This skill provides concise, practical guidelines for writing Rust documentation that is maintainable, consistent, and helpful to users. It emphasizes using intra-documentation links, minimizing duplication, and focusing on intent and API concepts rather than implementation details. The guidance helps keep docs stable as code evolves and improves discoverability of key concepts.

How this skill works

The skill inspects documentation patterns and recommends conventions to follow when authoring Rust doc comments and module-level explanations. It highlights when to use intra-doc links, how to reference constants and private items, and when to prefer conceptual explanations over line-level implementation notes. The result is documentation that is cross-referenced, resilient to refactors, and easier to read.

When to use it

When writing or reviewing public API documentation for Rust crates.
When documenting types, functions, constants, and traits to ensure consistent linking.
When updating docs after refactoring to avoid broken references and duplicated explanations.
When adding examples or comments inside function bodies that must remain stable across edits.
When deciding whether to explain a concept in-depth or to link to a single canonical explanation.

Best practices

Explain a key concept only once; link to that canonical section everywhere else using intra-doc links.
Always use intra-documentation links when referencing Rust symbols to keep links accurate during renames.
Avoid hard-coding constant values in docs; refer to constants with intra-doc links instead.
Prefer explaining why an API behaves a certain way; avoid repeating trivial implementation details.
Do not reference specific source line numbers; use inline comments attached to the relevant code if needed.
When linking to private items is useful, permit private intra-doc links with #[allow(rustdoc::private_intra_doc_links)].

Example use cases

Documenting a public struct and linking to its canonical explanation of invariants from multiple modules.
Refactoring an API while preserving documentation links by using intra-doc links instead of duplicated text.
Adding examples that show intended usage while keeping implementation commentary out of public docs.
Referencing configuration constants in docs so values update automatically when the constant changes.
Using inline comments for code-specific notes inside a function body rather than pointing to line numbers.

FAQ

Should I repeat a concept in multiple places for convenience?

No. Write the explanation once and use intra-doc links for every other mention to avoid drift and inconsistent wording.

Is it okay to mention constant values in docs?

Avoid hard-coding values. Link to the constant so documentation reflects updates automatically.