tn-write-crate-doc

name: tn-write-crate-doc description: | Generate crate-level documentation for telcoin-network crates. Trigger on: "document this crate", "write docs", "add rustdoc", "architecture doc", "module docs", "crate docs", "write crate documentation"

Crate Documentation Generator

Generate high-quality crate-level documentation for the telcoin-network repository -- a Rust blockchain node combining Narwhal/Bullshark DAG-based BFT consensus with EVM execution via Reth.

Project Context

The telcoin-network repo is a Cargo workspace combining Narwhal/Bullshark DAG-based BFT consensus with EVM execution via Reth. The workspace sets missing_docs = "warn" globally in [workspace.lints.rust] — all crates inherit this lint. Existing crate-level doc comments (//!) are terse, typically 1-3 lines in lib.rs. Some crates have README.md files of varying quality. The best documentation exemplar in the repo is crates/tn-reth/src/evm/tel_precompile/README.md.

Key architectural documents:

SYNC.md (repo root) — Epoch Chain and Consensus Chain synchronization strategy
crates/batch-builder/README.md — Detailed batch assembly, pool updates, security model

Process

Phase 1: Audit the target crate's documentation state

Read the crate's Cargo.toml to understand dependencies, features, and lint overrides
Read the crate's lib.rs to see existing //! doc comments and public API surface
List all .rs source files in the crate to understand module structure
Run cargo doc -p <crate-name> 2>&1 | grep "warning: missing" to find undocumented public items (use --no-deps to skip dependencies)
Check if the crate already has a README.md
Summarize findings: number of public items, percentage documented, module count

Phase 2: Read and understand the crate's architecture

Read every source file in the crate (use subagents for large crates)
Identify the crate's role in the overall system using the Project Context above
Map module dependencies and data flow within the crate
Identify key types, traits, and functions that form the public API
Check cross-crate dependencies to understand integration points
Read any referenced types/traits from other tn-* crates to understand the interfaces
Cross-reference with SYNC.md and other design docs if the crate touches consensus or sync

Phase 3: Generate documentation following the exemplar

Generate the documentation artifacts in this order:

Crate README.md -- The primary artifact. Follows the exemplar structure (see below). Write this first because it forces you to understand the crate deeply before writing inline docs.
Crate-level doc comments (//! in lib.rs) -- A concise summary (3-10 lines) with feature flags if applicable. Should align with README overview.
Module-level doc comments (//! at top of each module file) -- One-liner explaining the module's purpose.
Public item doc comments (/// on pub types, traits, functions, methods) -- Focus on items that cargo doc warns about. Include # Examples sections for non-obvious APIs.

Phase 4: Verify with cargo doc

Run cargo doc -p <crate-name> --no-deps 2>&1 and confirm warning count decreased
Run cargo test -p <crate-name> --doc to verify any doc examples compile
Review the generated HTML if accessible, or scan the doc output for broken links
Check that all cross-references ([TypeName]) resolve correctly

Documentation Types

Crate README.md

The primary documentation artifact. Lives at the crate root (e.g., crates/engine/README.md). Follows the exemplar structure below. This is what developers read first when encountering the crate.

Crate-level doc comments (`//!` in `lib.rs`)

Concise (3-10 lines). First line is a single-sentence summary. Additional lines explain the crate's role and link to the README for details. Include ## Feature Flags if the crate has non-trivial features.

Example from the repo:

//! The block builder maintains the transaction pool and builds the next block.
//!
//! The block builder listens for canonical state changes from the engine and updates the
//! transaction pool. These updates move transactions to the correct sub-pools. Only transactions in
//! the pending pool are considered for the next block.

Public item doc comments (`///`)

Every pub type, trait, function, and method should have a /// comment. Focus on the "why" not the "what" -- the type signature already tells you "what".

/// Executes a committed subdag from consensus, producing one EVM block per batch.
///
/// Each batch in the subdag becomes a separate block to support parallel basefees
/// once multiple workers are live. Empty subdags (no batches) still produce a
/// single block to accumulate leader rewards.
pub fn execute_consensus_output(/* ... */) -> Result</* ... */> {

Module-level doc comments (`//!`)

One to three lines at the top of each module file, after the SPDX header if present.

// SPDX-License-Identifier: MIT or Apache-2.0
//! Payload construction from consensus output.
//!
//! Converts committed batches into EVM block payloads with correct header fields.

Architecture diagrams (text-based)

Use simple ASCII/text diagrams for data flow. Keep them narrow (< 80 chars) for terminal readability.

Consensus Output ──> Engine ──> EVM Blocks ──> Canonical Chain
                        │
                        └──> Pool Updates ──> Batch Builder

Exemplar Structure

The tel_precompile README.md is the gold standard. Adapt this structure to each crate:

1. Title and Overview

# Crate Name -- One-line Description
1-2 paragraphs explaining what the crate does, its role in the system, and any important design decisions
Mention the core abstractions upfront

2. Module Map

Table with | File | Purpose | columns
One row per source file or significant module
Purpose should be a concise phrase, not a sentence

3. Data Flow / Lifecycle

Show how data moves through the crate
Use text diagrams, pseudocode, or step-by-step descriptions
For stateful crates: show state transitions
For processing crates: show the pipeline

4. Key Components (if applicable)

Describe the main types/traits and their responsibilities
Explain configuration options and feature flags
Document important constants or thresholds

5. Security Considerations

Threat models relevant to the crate
Trust assumptions
Critical invariants that must hold
Known limitations

6. Testing

How to run the crate's tests
Test infrastructure and utilities
Feature flags needed for testing
Integration test locations

Sections to include when relevant (not in every crate)

Storage Layout -- for crates with persistent state
Gas Costs -- for EVM-related crates
Access Control -- for crates with permissioned operations
Dependencies and Interfaces -- for crates with significant cross-crate integration

Conventions

Doc comment style

Use //! for crate and module-level docs
Use /// for item-level docs
First line is always a complete sentence ending with a period
Wrap at 100 characters (the repo convention)
Use backticks for code references: TypeName, function_name(), module::path
Every source file starts with // SPDX-License-Identifier: MIT or Apache-2.0 -- place //! docs after this line

Cross-references

Use intra-doc links: [TypeName], [module::TypeName]
For cross-crate references: [tn_types::ConsensusOutput]
For external crates: [reth_provider::BlockReader]
Test that links resolve by running cargo doc

Examples in doc comments

Include # Examples for public functions with non-obvious usage
Examples must compile (they run as doc tests)
Use # fn main() -> eyre::Result<()> { wrapper for examples needing error handling
Use # // hidden setup lines for boilerplate

README conventions

Use # for crate title, ## for sections, ### for subsections
Tables use GitHub-flavored markdown
Code blocks specify the language: ```rust, ```bash, ```text
No trailing whitespace
Single newline at end of file

Rules

Read before writing. Always complete Phase 1 and Phase 2 before generating any documentation. You cannot write accurate docs without understanding the code.
Accuracy over completeness. Never invent behavior. If you are uncertain about what a function does, read the implementation. If you are still uncertain, document what you can verify and leave a TODO: comment for the rest.
Follow the exemplar. The tel_precompile README.md is the quality bar. Match its depth, specificity, and structure. Generic hand-wavy descriptions are not acceptable.
Preserve existing docs. Do not delete or rewrite existing doc comments unless they are factually wrong. Extend them. If a lib.rs already has //! comments, add to them rather than replacing.
No empty sections. If a section from the exemplar structure does not apply to the target crate, omit it entirely. Do not write "N/A" or placeholder text.
Test your examples. Any code in doc comments must compile. Run cargo test -p <crate> --doc before declaring the task complete.
Use subagents for large crates. If a crate has more than 10 source files, dispatch subagents to read and summarize modules in parallel. Synthesize their findings before writing.
Security sections are mandatory. Every crate that handles consensus, networking, keys, or state must have a Security Considerations section. For pure utility crates, this section may be omitted.
Verify with cargo doc. Always run cargo doc -p <crate-name> --no-deps after adding docs and report the warning count before and after.
Match the repo voice. The existing documentation is direct and technical -- no marketing language, no hedging ("might", "could potentially"), no filler. State facts plainly.
One commit per crate. When documenting a crate, all documentation changes for that crate go in a single commit. Do not mix documentation for multiple crates in one commit.
Do not create files that already exist without reading them first. If a README.md already exists for the crate, read it, then extend or improve it rather than overwriting.