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