documenting-rust-code
Rust documentation practices for HASH codebase. Use when writing doc comments, documenting functions/types/traits/modules, creating error sections, using intra-doc links, or following rustdoc conventions.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-06-28
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- documenting-rust-code
- license
- AGPL-3.0
- metadata
- { "triggers": { "type": "domain", "keywords": [ "rustdoc", "doc comment", "documentation", "intra-doc link" ], "priority": "high", "enforcement": "suggest", "intent-patterns": [ "\\bdocument(ing|ation)?\\b.*?\\b(rust|function|type|struct|enum|trait|module)\\b", "\\b(write|add|create)\\b.*?\\bdoc\\s*comment\\b", "\\b#\\s*(Errors|Panics|Examples|Arguments)\\b" ] } }
- description
- Rust documentation practices for HASH codebase. Use when writing doc comments, documenting functions/types/traits/modules, creating error sections, using intra-doc links, or following rustdoc conventions.
02 资源文件 5
- 参考文档README.md826 B
- 参考文档references/error-documentation.md5.0 KB
- 参考文档references/examples-and-links.md6.5 KB
- 参考文档references/function-documentation.md7.1 KB
- 参考文档references/type-documentation.md5.2 KB
03 SKILL.md 正文
Rust Documentation Practices
Comprehensive guidance on documenting Rust code in the HASH repository following rustdoc conventions.
Core Principles
Follow high-quality standards like time, jiff, and serde:
✅ DO:
- Begin every doc comment with single-line summary
- Use intra-doc links for all type references
- Document all error conditions with
# Errors - Include practical examples for public APIs
- Link standard library types: [
Vec], [HashMap], etc. - Use inline parameter descriptions for simple functions (0-2 params)
- Describe return values in main text, not separate sections
❌ DON'T:
- Document standard trait implementations (
Debug,Display,From) - Add separate
# Returnssections (inline instead) - Mention variable types already in signatures
- Use comments on same line as code
- Skip error documentation for fallible functions
Quick Reference
Basic Doc Comment
/// Retrieves an entity by its UUID.
///
/// Loads the entity from the store and verifies access permissions.
/// Returns the [`Entity`] if found and accessible.
///
/// # Errors
///
/// - [`NotFound`] if the entity doesn't exist
/// - [`AuthorizationError`] if access is denied
///
/// [`NotFound`]: EntityError::NotFound
/// [`AuthorizationError`]: EntityError::Authorization
pub fn get_entity(&self, id: EntityId) -> Result<Entity, Report<EntityError>> {
Intra-Doc Links
/// Updates the [`User`] using [`UserUpdateStrategy`].
///
/// See [`validation::user`] for validation rules.
///
/// [`validation::user`]: crate::validation::user
Documentation Patterns
Simple Functions (0-2 params)
Describe parameters inline:
/// Processes the `input` elements and returns filtered results.
///
/// Takes a collection of `input` elements, applies the `filter_fn`,
/// and returns a [`Vec`] containing only matching elements.
Complex Functions (3+ params)
Use explicit # Arguments section:
/// Merges multiple data sources with transformation rules.
///
/// # Arguments
///
/// * `sources` - Collection of data sources to merge
/// * `rules` - Transformation rules to apply
/// * `options` - Configuration controlling merge behavior
/// * `callback` - Optional function for each merged item
Error Documentation
/// # Errors
///
/// - [`WebAlreadyExists`] if web ID is taken
/// - [`AuthorizationError`] if permission denied
///
/// [`WebAlreadyExists`]: WebError::WebAlreadyExists
/// [`AuthorizationError`]: WebError::Authorization
Module Documentation
//! Entity management functionality.
//!
//! Main types:
//! - [`Entity`] - Core entity type
//! - [`EntityStore`] - Storage trait
//!
//! # Examples
//!
//! ```
//! use hash_graph::entity::Entity;
//! ```
Examples with Error Handling
/// # Examples
///
/// ```rust
/// let entities = get_entities_by_type(type_id)?;
/// assert_eq!(entities.len(), 2);
/// # Ok::<(), Box<dyn core::error::Error>>(())
/// ```
Verification
cargo doc --no-deps --all-features
References
- references/function-documentation.md: Functions and methods documentation patterns
- references/type-documentation.md: Types, structs, enums, and traits documentation
- references/error-documentation.md: Error conditions and panics documentation
- references/examples-and-links.md: Examples and intra-doc links usage
04 同仓库更多 Skills
rhaios-staging
Interact with the Rhaios staging REST API for yield operations. Discover -> prepare -> setup-if-needed -> sign -> execute flow with pluggable signer backend. Triggers on requests involving DeFi yield, vault deposits, redeems, rebalancing, or Rhaios API.
git-commit-push
Commit and push repository changes safely. Use when user asks to commit, push, or verify and push current changes.
exec-slurm-compile
Compile TensorRT-LLM on a SLURM cluster. Covers submitting a batch job with a container image, monitoring the job, and verifying the build. Use when the user wants to compile TRT-LLM remotely via SLURM rather than on a local compute node.
databases
Work with MongoDB (document database, BSON documents, aggregation pipelines, Atlas cloud) and PostgreSQL (relational database, SQL queries, psql CLI, pgAdmin). Use when designing database schemas, writing queries and aggregations, optimizing indexes for performance, performing database migrations, configuring replication and sharding, implementing backup and restore strategies, managing database users and permissions, analyzing query performance, or administering production databases.
toast
Toast — restaurant POS, orders, menus, employees, revenue centers, and reporting.
k-schoollunch-menu
Use when the user asks for Korean school meal menus (급식 식단) by natural-language education office and school name, via k-skill-proxy NEIS school-search and school-meal routes.