name: documentation description: Guide for generating and maintaining contract documentation from JSON schemas. Use when creating schemas, generating docs, or documenting contract APIs. license: BSD-3-Clause metadata: author: axone.xyz version: "1.0"

Contract Documentation Generation

This skill helps you generate and maintain documentation for Axone protocol smart contracts from JSON schemas.

When to use this skill

Use this skill when you need to:

• Generate JSON schemas from message types
• Create markdown documentation from schemas
• Document contract APIs
• Update documentation after contract changes
• Follow documentation best practices

Documentation Pipeline

Rust Types → JSON Schema → Markdown Docs
   ↓              ↓              ↓
 msg.rs    module-schema.json   docs/*.md

Step 1: Generate Schemas

cargo make schema

This runs the schema binary for each contract, producing:

contracts/<name>/schema/module-schema.json

Step 2: Generate Documentation

cargo make docs

This:

1. Collects schemas from all contracts
2. Processes them with @fadroma/schema
3. Formats output with Prettier
4. Outputs to docs/ directory

One Command

cargo make docs  # Runs schema generation automatically

Schema Generation

Binary Setup

Each contract has a schema binary at src/bin/schema.rs:

use cosmwasm_schema::write_api;
use my_contract::msg::{
    ExecuteMsg, InstantiateMsg, MigrateMsg, QueryMsg,
};

fn main() {
    write_api! {
        instantiate: InstantiateMsg,
        execute: ExecuteMsg,
        query: QueryMsg,
        migrate: MigrateMsg,
    }
}

Running for Single Contract

cd contracts/axone-gov
cargo make schema

Writing Documentation-Ready Code

Message Documentation

Every message type and field must have doc comments:

/// Contract execution messages for the governance module.
/// 
/// These messages modify contract state and require authorization.
#[cosmwasm_schema::cw_serde]
#[derive(cw_orch::ExecuteFns)]
pub enum ExecuteMsg {
    /// Create a new proposal for voting.
    /// 
    /// Only accounts with proposal rights can call this.
    /// The proposal enters the voting period immediately.
    CreateProposal {
        /// Title of the proposal (max 256 chars)
        title: String,

        /// Detailed description of what the proposal does
        description: String,

        /// Messages to execute if the proposal passes
        msgs: Vec<CosmosMsg>,
    },

    /// Cast a vote on an active proposal.
    Vote {
        /// ID of the proposal to vote on
        proposal_id: u64,

        /// The vote choice
        vote: VoteOption,
    },
}

Response Types

/// Response for the Config query.
/// 
/// Contains the current configuration of the governance module.
#[cosmwasm_schema::cw_serde]
pub struct ConfigResponse {
    /// Address of the governance admin
    pub admin: Addr,

    /// Minimum voting period in seconds
    pub voting_period: u64,

    /// Quorum percentage required for proposals (0-100)
    pub quorum: u8,
}

Enum Variants

/// Options for casting a vote.
#[cosmwasm_schema::cw_serde]
pub enum VoteOption {
    /// Vote in favor of the proposal
    Yes,

    /// Vote against the proposal  
    No,

    /// Abstain from voting but count toward quorum
    Abstain,

    /// Strong opposition that vetoes the proposal
    NoWithVeto,
}

Schema Structure

The generated module-schema.json follows this structure:

{
  "contract_name": "axone-gov",
  "contract_version": "8.0.0",
  "idl_version": "1.0.0",
  "instantiate": { ... },
  "execute": { ... },
  "query": { ... },
  "migrate": { ... },
  "responses": { ... }
}

Documentation Best Practices

1. Be Concise but Complete

// ✅ Good
/// Create a new governance proposal for community voting.

// ❌ Too brief
/// Create proposal.

// ❌ Too verbose
/// This function is used to create a new governance proposal 
/// that will be submitted to the community for voting purposes.

2. Document Constraints

/// Title of the proposal.
/// 
/// Must be between 1 and 256 characters.
/// Cannot contain newlines.
pub title: String,

3. Document Default Values

/// Maximum number of items to return.
/// 
/// Defaults to 10 if not specified. Maximum allowed is 100.
#[serde(default = "default_limit")]
pub limit: Option<u32>,

4. Cross-Reference Related Items

/// Execute a passed proposal.
/// 
/// Can only be called after the proposal passes.
/// See [`CreateProposal`] for proposal creation.
/// See [`Vote`] for casting votes.
ExecuteProposal { proposal_id: u64 },

Commit Documentation Changes

When updating contracts, always regenerate and commit docs:

cargo make docs
git add docs/
git commit -m "docs: update generated documentation"

Documentation Checklist

• [ ] All message types have doc comments
• [ ] All struct fields are documented
• [ ] Constraints are documented (min/max, format)
• [ ] Default values are noted
• [ ] Error conditions are described
• [ ] Schemas generate without errors (cargo make schema)
• [ ] Docs generate without errors (cargo make docs)
• [ ] Changes committed with conventional commit message