| 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.
