mcpField
R
rust-docs-guidelines

rust-docs-guidelines

github.com/redisearchDevelopment6.2k60 installsUpdated today
Repository

About rust-docs-guidelines

A skill providing standards for writing Rust documentation. It covers symbol links, safety wording, and guidance on explaining concepts and implementation details.

Key features

  1. 01Links Rust symbols within documentation
  2. 02Specifies pointer-validity link wording
  3. 03Guides safety and callback documentation
  4. 04Discourages brittle line references

Use cases

  1. 01Write Rust API documentation
  2. 02Review Rust safety documentation
  3. 03Keep explanations focused and maintainable

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/redisearch/redisearch --skill rust-docs-guidelines

After installing, type/rust-docs-guidelinesin Claude Code to confirm it loaded.

Details

From the project README

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.).
  • In a # Safety section, link the word valid to std's pointer-validity rules: write it as [valid] and put this reference definition at the end of the doc block — 
    [valid]: https://doc.rust-lang.org/std/ptr/index.html#safety
    Only where it means pointer or memory validity — valid UTF-8, a valid enum variant, a valid nul terminator and a by-value struct whose fields must agree keep their plain form, since std's definition says nothing about them. A duration clause such as "must remain valid for the lifetime of the returned iterator" does mean it, so link it as well; the duration it adds is orthogonal to what validity means. A callback parameter is the other way round: std's rules cover accesses through data pointers, not whether an address is callable under a given ABI, so require the signature to be [ABI-compatible] instead and define it as — 
    [ABI-compatible]: https://doc.rust-lang.org/std/primitive.fn.html#abi-compatibility
    Non-doc // SAFETY: comments keep the plain form too: rustdoc does not render them, so the brackets would stay literal text.
  • 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.

Comments

Markdown supported