API docs parity: Rust

[edburns]

Rust API Docs

Parent epic: #1653

Doc format: /// and //! doc comments with Markdown. cargo doc generates HTML locally; #[doc] attributes are first-class in the language.

Culture: Extremely strong — arguably the strongest of all ecosystems. Missing docs on public items trigger #![warn(missing_docs)]. Examples in doc comments are compiled and run as tests (cargo test runs doctests).

Hosting analogues:

Service	How it works
docs.rs	Official, run by the Rust infrastructure team. Automatically builds and hosts docs for every crate published to crates.io. Direct equivalent of javadoc.io, but first-party

Key difference from Java: docs.rs is fully automatic and authoritative — no opt-in, no separate artifact. Publishing to crates.io triggers a docs build within minutes.

[github-actions]

Documentation Gap Summary

This issue tracks API documentation parity for the Rust SDK (part of the docs parity epic #1653).

What's missing / needs improvement

The Rust SDK (rust/) already has some scaffolding in place:

• #![warn(missing_docs)] and #![deny(rustdoc::broken_intra_doc_links)] in rust/src/lib.rs
• documentation = "(docs.rs/redacted) in Cargo.toml`
• Module-level /// comments in lib.rs
• Partial doc comments in session.rs and tool.rs

However, the following is incomplete or missing:

1. /// doc comments on all public structs, enums, functions, and methods — Session, SessionUi, and the public API surface in session.rs, tool.rs, hooks.rs, handler.rs, permission.rs, canvas.rs, rpc.rs, session_fs.rs, transforms.rs, trace_context.rs, types.rs need complete coverage.
2. Doctest examples — Rust's cargo test compiles and runs code in doc comments. High-value public APIs (e.g., Client::create_session, tool definition helpers, schema_for) should include # Examples sections with runnable doctests.
3. //! module-level docs — inner module docs (crate-root summary, per-module overview) describing purpose and usage pattern.
4. rust/README.md coverage — the README is pulled into crate docs via #![doc = include_str!("../README.md")]; any gaps in the README surface directly on docs.rs.

Affected files / sections

File	Gap
rust/src/session.rs	Session and SessionUi struct fields, all public methods
rust/src/tool.rs	Tool, ToolSet, DefineTool pattern examples
rust/src/hooks.rs	Hook trait/callback docs and examples
rust/src/handler.rs	PermissionHandler and event handler traits
rust/src/canvas.rs	Canvas provider types and callbacks
rust/src/rpc.rs	RPC namespace builder API
rust/src/session_fs.rs	Virtual filesystem provider API
rust/src/types.rs	Shared protocol types
rust/src/errors.rs	Error kinds and recovery guidance
rust/README.md	Quickstart examples, feature flags, docs.rs badge

Suggested content to add

• Add /// (description) doc comments to every public item flagged by #![warn(missing_docs)] — run cargo doc 2>&1 | grep "missing documentation" to enumerate them.
• Add # Examples with doctests to the most commonly-used APIs (Client::new, Client::create_session, tool definitions).
• Add a docs.rs badge to rust/README.md: `[(docs.rs/redacted)
• Verify docs build cleanly with cargo doc --all-features --no-deps locally before publishing.

Generated by Documentation Handler for issue #1658 · sonnet46 497.2K · ◷