api-doc-comments
/api-doc-comments
Guide for writing Rust doc comments that produce accurate generated contract documentation. Use when editing Instantiate/Execute/Query/Response types or any public schema-facing API.
- Author
- axone-protocol ↗
- Repository
- contracts ↗
- Licence
- BSD-3-Clause
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
BSD-3-Clause, otwarta.
What it does and when to use it
Guide for writing Rust doc comments that produce accurate generated contract documentation. Use when editing Instantiate/Execute/Query/Response types or any public schema-facing API.
Original author description
Guide for writing Rust doc comments that produce accurate generated contract documentation. Use when editing Instantiate/Execute/Query/Response types or any public schema-facing API.
How it works
- Core Rule
- What must be documented
- Writing Style
- What good API comments should explain
- Repo-Specific Guidance
- Recommended Comment Shapes
- Examples of useful details
- Relationship with other skills
SKILL.md preview
--- name: api-doc-comments description: Guide for writing Rust doc comments that produce accurate generated contract documentation. Use when editing Instantiate/Execute/Query/Response types or any public schema-facing API. license: BSD-3-Clause metadata: author: axone.xyz version: "1.0" --- # API Doc Comments ## Core Rule The generated documentation is only as good as the Rust doc comments on schema-facing types. Write the comments on the source types first, then regenerate docs with the doc-generation workflow. ## What must be documented Document all schema-facing public items: - message structs and enums - execute/query variants - every public field in those messages - query response structs - domain-specific public enums surfaced through the schema ## Writing Style Prefer comments that are: - specific to the contract's domain - precise about behavior - concise, but not cryptic - written from the caller's point of view Avoid comments that are: - generic restatements of the field name - implementation-oriented when the caller needs semantics - padded with filler text ## What good API comments should explain ### Semantics Explain what the message or field means in the protocol, not only its Rust type. ### Preconditions and invariants Document constraints such as: - accepted formats - authorization requirements - default behaviors - ordering or pagination semantics - exact conditions under which an action is permitted ### Encoded representations When the public API intentionally uses `String` or `Binary`, document the encoded format explicitly. Examples from this repository include: - Prolog case terms carried as `String` - constitutions carried as UTF-8 Prolog bytes in `Binary` - DIDs represented as canonical strings - hashes exposed as binary values with a named algorithm ### Domain examples Use short examples when the payload format is not self-evident, especially for: - Prolog terms - CAIP / DID-like identifiers - structured intent names ## Repo-Specific Guidance For Axone contracts, strong API comments often need to explain: - how a resource relates to its host Abstract Account - what data is caller-provided versus injected by the contract - which keys are authoritative when contexts are merged - which governance intent is being evaluated - what a returned verdict or motivation represents These semantics matter more than low-level implementation detail. ## Recommended Comment Shapes ### Top-level message types - one short summary line - one or more paragraphs for domain semantics - preconditions or protocol rules when relevant ### Enum variants - what the action or query does - when it should be used - important side effects or gating rules ### Fields - what the field contains - expected format or units - default or optional behavior if applicable ## Examples of useful details Good details to include: - "UTF-8 Prolog program bytes" - "exclusive pagination cursor" - "verdict returned by `governance:decide/3`" - "canonical Cosmos Bech32 account rendered in DID form" Weak details to avoid: - "The title" - "A string value" - "Used for execution" ## Relationship with other skills - Use `api-design` to shape the contract surface itself. - Use this skill to make that surface intelligible in generated documentation. - Use `doc-generation` after comment changes to refresh generated artifacts.
Versions
The database has no other skills named api-doc-comments.
Database snapshot: 13.11.2026 · package version 2637fceaf0c9 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100code-comments
Write, review, or remove code comments. Use when adding comments or doc comments, reviewing the comments in a diff, or cleaning up or removing comments. - 100writing-xml-doc-comments
Write or review C# XML documentation comments on public API surface. USE FOR: adding or reviewing XML documentation on public types, members, parameters, type parameters, and return values. DO NOT USE FOR: ordinary code comments (use csharp-style), or prose, markdown, README,… - 100go-documentation
Use when writing or reviewing Go doc comments, or creating exported types, functions, or packages even without a documentation request. Internal code comments belong to go-style-core. - 100documenting-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. - 100doc-generator
Generate comprehensive, accurate API documentation from source code. Use when creating or updating API documentation, generating OpenAPI specs, or when users mention API docs, endpoints, or documentation. - 100code-documentation
Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides.