Przejdź do treści
Biblioteka skilli
Programowanie · Pisanie

api-doc-comments

/api-doc-comments

Pomaga pisać komentarze dokumentacyjne w Rust, które dają dokładną wygenerowaną dokumentację kontraktu, dla typów Instantiate, Execute, Query i Response oraz publicznych API schematu.

Repozytorium
contracts ↗
Licencja
BSD-3-Clause
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

BSD-3-Clause, otwarta.

Co robi i kiedy

Pomaga pisać komentarze dokumentacyjne w Rust, które dają dokładną wygenerowaną dokumentację kontraktu, dla typów Instantiate, Execute, Query i Response oraz publicznych API schematu.

Oryginalny opis (EN)

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.

Jak działa

  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
Sekcje z nagłówków SKILL.md, w oryginale · 122 linii, 481 słów
Podgląd SKILL.md
---
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.

Wersje

W bazie nie ma innych skilli o nazwie api-doc-comments.

Migawka bazy z 13.11.2026 · wersja paczki 2637fceaf0c9 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100code-comments
    Pisze, przegląda i usuwa komentarze w kodzie oraz komentarze dokumentacyjne, także w diffach.
  • 100writing-xml-doc-comments
    Pisze i przegląda komentarze dokumentacyjne XML w C# dla publicznego API, z opisem parametrów i wartości zwracanych.
  • 100go-documentation
    Pomaga pisać i recenzować komentarze doc w Go oraz tworzyć eksportowane typy, funkcje i pakiety, także bez prośby o dokumentację.
  • 100documenting-rust-code
    Opisuje praktyki dokumentowania kodu Rust w repozytorium HASH: komentarze dokumentacyjne funkcji, typów, traitów i modułów, sekcje błędów, linki intra-doc i konwencje rustdoc.
  • 100doc-generator
    Generuje dokładną dokumentację API ze źródeł kodu, w tym specyfikacje OpenAPI, przy tworzeniu i aktualizowaniu opisów endpointów.
  • 100code-documentation
    Pomaga pisać dokumentację kodu: README, dokumentację API, komentarze i przewodniki dla programistów.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.