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.
- Autor
- axone-protocol ↗
- Repozytorium
- contracts ↗
- Licencja
- BSD-3-Clause
- Ostatnia zmiana repozytorium
- 27.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.
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
- Core Rule
- What must be documented
- Writing Style
- What good API comments should explain
- Repo-Specific Guidance
- Recommended Comment Shapes
- Examples of useful details
- Relationship with other skills
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.