AGENT SKILL

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

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 # Returns sections (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

04 同仓库更多 Skills

vdcworkshop
vdcworkshop/Skills-Catalog

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.

★ 1
vdcworkshop
vdcworkshop/Skills-Catalog

git-commit-push

Commit and push repository changes safely. Use when user asks to commit, push, or verify and push current changes.

★ 1
vdcworkshop
vdcworkshop/Skills-Catalog

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.

★ 1
vdcworkshop
vdcworkshop/Skills-Catalog

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.

★ 1
vdcworkshop
vdcworkshop/Skills-Catalog

toast

Toast — restaurant POS, orders, menus, employees, revenue centers, and reporting.

★ 1
vdcworkshop
vdcworkshop/Skills-Catalog

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.

★ 1