Skip to content
Skills Library
Programming · Writing

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.

Repository
contracts ↗
Licence
BSD-3-Clause
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

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

  1. Core Rule
  2. What must be documented
  3. Writing Style
  4. What good API comments should explain
  5. Repo-Specific Guidance
  6. Recommended Comment Shapes
  7. Examples of useful details
  8. Relationship with other skills
Original SKILL.md headings · 122 lines, 481 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.