docs: improve API documentation

[Tim-Zhang]

Summary

• redesign the crate landing page around getting started, runtime selection, and an API tour
• document public APIs across the sync, async, streaming, transport, compiler, and codegen crates
• add rustdoc lint guards and compiled documentation examples

Why

The existing API documentation was sparse and did not clearly explain the code generation workflow, runtime choices, feature flags, transport support, or failure semantics. This update makes docs.rs useful as both an onboarding guide and an API reference.

This is a documentation-only change and does not alter runtime behavior.

Validation

• RUSTDOCFLAGS='-D missing_docs -D rustdoc::broken_intra_doc_links' cargo doc --workspace --all-features --no-deps
• default-feature and async-only rustdoc builds with -D warnings
• cargo test --workspace --all-features --doc
• make check-all
• git diff --check

[Copilot]

🟡 Changes recommended

A stray unindented /// in src/asynchronous/shutdown.rs is likely to trigger warnings/errors under -D warnings rustdoc builds.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Pull request overview

This PR significantly expands and modernizes the rustdoc surface across the workspace (crate landing pages, public APIs, and examples) and adds rustdoc lint guards to keep documentation quality high going forward.

Changes:

• Rewrites crate/module-level docs to focus on onboarding (getting started, runtime selection, transport addresses) and API “tours”.
• Adds/updates rustdoc for many public types and methods across sync/async runtimes, streaming, transports, framing, and codegen/compiler crates.
• Enables rustdoc linting via #![warn(missing_docs)] and #![warn(rustdoc::broken_intra_doc_links)], and adds a dev-dependency to support doc tests/examples.

File summaries

File	Description
ttrpc-codegen/src/lib.rs	Adds crate-level docs, examples, and missing-docs/broken-link lint warnings for codegen APIs.
src/sync/utils.rs	Documents sync request context and generated dispatch traits.
src/sync/server.rs	Expands sync Server docs with examples, error/panic semantics, and configuration details.
src/sync/mod.rs	Adds module overview docs for the sync runtime.
src/sync/client.rs	Documents sync Client behavior, ownership, and request failure modes.
src/proto.rs	Documents framing constants, headers, frame types, and codec traits.
src/lib.rs	Redesigns crate landing page (getting started, runtime choice, transports, security) and enables rustdoc lints.
src/error.rs	Improves error type and helper function documentation.
src/context.rs	Documents request context semantics, metadata behavior, and conversion helpers.
src/asynchronous/utils.rs	Documents async handler traits and async request context.
src/asynchronous/transport/windows.rs	Documents named-pipe bind/connect helpers.
src/asynchronous/transport/vsock.rs	Documents vsock bind/connect helpers and FD safety/ownership.
src/asynchronous/transport/unix.rs	Documents unix bind/connect helpers and FD safety/ownership.
src/asynchronous/transport/tcp.rs	Documents async TCP transport helpers (Unix-only via module cfg).
src/asynchronous/transport/mod.rs	Adds module overview and documents transport extension points and address binding/connection APIs.
src/asynchronous/stream.rs	Documents streaming handle types, split semantics, and error cases.
src/asynchronous/shutdown.rs	Adds module overview and documents shutdown coordination primitives.
src/asynchronous/server.rs	Documents async Server lifecycle, listener ownership, registration behavior, and failure modes.
src/asynchronous/mod.rs	Adds async runtime module overview and clarifies runtime requirements.
src/asynchronous/client.rs	Documents async Client behavior, runtime requirements, and request/streaming APIs.
compiler/src/prost_codegen.rs	Adds module-level docs and documents failure semantics for legacy protoc/prost pipeline.
compiler/src/lib.rs	Adds crate-level docs plus rustdoc lint warnings; improves public API field docs.
compiler/src/codegen.rs	Documents key public generator entry points and their error/panic semantics.
compiler/src/bin/ttrpc_rust_plugin.rs	Documents the protoc plugin binary entry point.
Cargo.toml	Adds ttrpc-codegen as a dev-dependency for workspace doc tests/examples.

Review details

• Files reviewed: 25/25 changed files
• Comments generated: 2
• Review effort level: Lite

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/error.rs:94

• SOCK_DICONNECTED is misspelled; since it is used locally, renaming it to SOCK_DISCONNECTED improves clarity without affecting the public API.

const SOCK_DICONNECTED: &str = "socket disconnected";
/// Converts a low-level socket read result into a ttrpc error.
///
/// A zero-byte read is reported as a disconnected socket. Other failures become an
/// `INVALID_ARGUMENT` RPC status containing `msg`.

ttrpc-codegen/src/lib.rs:32

• The docs claim Codegen::run uses Cargo's OUT_DIR when out_dir is unset, but the implementation falls back to the current working directory when OUT_DIR is missing. Clarify the fallback to avoid misleading non-Cargo callers.

//! When no output directory is configured, [`Codegen::run`] uses Cargo's `OUT_DIR` environment
//! variable. Generated module declarations can then be included with:

src/asynchronous/stream.rs:496

• The docs mention a misspelled identifier (recveivable). Since this is prose, consider avoiding the identifier entirely and describe the flags generically to prevent propagating the typo.

    /// `sendable` and `recveivable` describe the permitted directions, while `kind` controls the
    /// client- or server-side close semantics. This constructor is intended for generated bindings