api-doc-comments

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.