Document every published crate

README.md

@@ -194,11 +194,12 @@ for a team, start small, and use the worked examples on the
 
 The [website](https://contextgeneric.dev/) is the main documentation: the quickstart, the tutorials,
 the concepts, the construct reference, the comparisons, and the project pages. The crates' API
-documentation on [docs.rs](https://docs.rs/cgp) covers the items themselves.
+documentation on [docs.rs](https://docs.rs/cgp) is the place to look up an item.
 
 > [!NOTE]
-> The crates' API docs on `docs.rs` are still sparse. The website is the place to start while the
-> inline documentation is filled in.
+> Each crate's `docs.rs` page says what that crate provides and links the reference page for its
+> constructs. The per-item documentation is still being filled in, so the website remains the place
+> to start.
 
 Contributors and coding agents have a second, deeper source: the
 [CGP knowledge base](https://github.com/contextgeneric/cgp-knowledge-base), which holds the

crates/core/cgp-base-types/Cargo.toml

@@ -9,6 +9,6 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "CGP's type-level primitives: symbols, lists, sums, and paths."
 
 [dependencies]

crates/core/cgp-base-types/src/lib.rs

@@ -1,3 +1,7 @@
+//! This crate provides CGP's type-level primitives: symbols, lists, sums, and paths.
+//!
+//! See [`Symbol!`](https://contextgeneric.dev/docs/reference/macros/symbol), [`Cons`](https://contextgeneric.dev/docs/reference/types/cons), [`Nil`](https://contextgeneric.dev/docs/reference/types/nil), [`Chars`](https://contextgeneric.dev/docs/reference/types/chars), [`PathCons`](https://contextgeneric.dev/docs/reference/types/path_cons), [`StaticFormat`](https://contextgeneric.dev/docs/reference/traits/formatting/static_format), and [`ConcatPath`](https://contextgeneric.dev/docs/reference/traits/formatting/concat_path).
+
 pub mod macro_prelude;
 pub mod traits;
 pub mod types;

crates/core/cgp-base-types/src/types/cons.rs

@@ -2,7 +2,7 @@
     The `Cons` type is used to represent the head of a _type-level list_,
     also known as an _anonymous product type_.
 
-    `Cons` is used together with [`Nil`] to produce a type-level list using
+    `Cons` is used together with [`Nil`](crate::types::Nil) to produce a type-level list using
     the `Product!` macro.
 
     ## Example

crates/core/cgp-base-types/src/types/nil.rs

@@ -2,10 +2,10 @@
     The `Nil` type is used to represent the end of a _type-level list_,
     or an empty type-level list.
 
-    `Nil` is commonly used as the `Tail` of a [`Cons`] type, to terminate the list.
+    `Nil` is commonly used as the `Tail` of a [`Cons`](crate::types::Cons) type, to terminate the list.
     When used on its own, it represents an empty type-level list.
 
-    Read more about type-level lists, a.k.a. the product types, in [`Cons`].
+    Read more about type-level lists, a.k.a. the product types, in [`Cons`](crate::types::Cons).
 */
 #[derive(Eq, PartialEq, Clone, Default, Debug)]
 pub struct Nil;

crates/core/cgp-component/Cargo.toml

@@ -9,6 +9,6 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "CGP's component machinery: delegation, provider lookup, and the built-in providers."
 
 [dependencies]

crates/core/cgp-component/src/lib.rs

@@ -1,9 +1,8 @@
 #![no_std]
-
-/*!
-   This crate defines the core CGP types and traits used to enable the core
-   CGP component implementation.
-*/
+//! This crate provides CGP's component machinery: delegation, provider lookup, and the built-in
+//! providers.
+//!
+//! See [`DelegateComponent`](https://contextgeneric.dev/docs/reference/traits/wiring/delegate_component), [`IsProviderFor`](https://contextgeneric.dev/docs/reference/traits/wiring/is_provider_for), [`CanUseComponent`](https://contextgeneric.dev/docs/reference/traits/wiring/can_use_component), [`UseContext`](https://contextgeneric.dev/docs/reference/providers/use_context), [`UseDefault`](https://contextgeneric.dev/docs/reference/providers/use_default), [`UseDelegate`](https://contextgeneric.dev/docs/reference/providers/use_delegate), and [`RedirectLookup`](https://contextgeneric.dev/docs/reference/providers/redirect_lookup).
 
 pub mod macro_prelude;
 

crates/core/cgp-error/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "CGP's error components: the abstract error type, raising, and wrapping."
 
 [dependencies]
 cgp                 = { version = "0.8.0-alpha", path = "../../main/cgp-base-extra", package = "cgp-base-extra" }

crates/core/cgp-error/src/lib.rs

@@ -1,4 +1,7 @@
 #![no_std]
+//! This crate provides CGP's error components: the abstract error type, raising, and wrapping.
+//!
+//! See [`HasErrorType`](https://contextgeneric.dev/docs/reference/components/has_error_type), [`CanRaiseError`](https://contextgeneric.dev/docs/reference/components/can_raise_error), and [`CanWrapError`](https://contextgeneric.dev/docs/reference/components/can_wrap_error).
 
 mod contexts;
 mod traits;

crates/core/cgp-field/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "CGP's field access: the field traits, the field tags, the type-level lists, and the structural casts."
 
 [dependencies]
 cgp-base-types      = { workspace = true }

crates/core/cgp-field/src/lib.rs

@@ -1,4 +1,8 @@
 #![no_std]
+//! This crate provides CGP's field access: the field traits, the field tags, the type-level lists,
+//! and the structural casts.
+//!
+//! See [`HasField`](https://contextgeneric.dev/docs/reference/traits/field-access/has_field), [`Index`](https://contextgeneric.dev/docs/reference/types/index_type), [`MRef`](https://contextgeneric.dev/docs/reference/types/mref), and the [casts](https://contextgeneric.dev/docs/reference/traits/casting/).
 
 pub mod impls;
 pub mod traits;

crates/core/cgp-type/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "CGP's abstract types: a type the context chooses behind a trait."
 
 [dependencies]
 cgp                 = { version = "0.8.0-alpha", path = "../../main/cgp-base", package = "cgp-base" }

crates/core/cgp-type/src/lib.rs

@@ -1,4 +1,7 @@
 #![no_std]
+//! This crate provides CGP's abstract types: a type the context chooses behind a trait.
+//!
+//! See [`HasType`](https://contextgeneric.dev/docs/reference/components/has_type), [`UseType`](https://contextgeneric.dev/docs/reference/providers/use_type), and [`UseDelegatedType`](https://contextgeneric.dev/docs/reference/providers/use_delegated_type).
 
 mod impls;
 mod traits;

crates/extra/cgp-dispatch/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "CGP's dispatch providers, which match, extract, and build a value on the way to a handler."
 
 [dependencies]
 cgp         = { version = "0.8.0-alpha", path = "../../main/cgp-core", package = "cgp-core" }

crates/extra/cgp-dispatch/src/lib.rs

@@ -1,5 +1,9 @@
 #![no_std]
 #![allow(clippy::needless_lifetimes)]
+//! This crate provides CGP's dispatch providers, which match, extract, and build a value on the way
+//! to a handler.
+//!
+//! See [`MatchWithHandlers`](https://contextgeneric.dev/docs/reference/providers/dispatch/match_with_handlers), [`MatchWithValueHandlers`](https://contextgeneric.dev/docs/reference/providers/dispatch/match_with_value_handlers), and [`ExtractFieldAndHandle`](https://contextgeneric.dev/docs/reference/providers/dispatch/extract_field_and_handle).
 
 mod providers;
 

crates/extra/cgp-error-extra/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "CGP's generic error providers, which raise, return, discard, and format an error."
 
 [features]
 default = [ "alloc" ]

crates/extra/cgp-error-extra/src/lib.rs

@@ -1,4 +1,8 @@
 #![no_std]
+//! This crate provides CGP's generic error providers, which raise, return, discard, and format an
+//! error.
+//!
+//! See [`RaiseFrom`](https://contextgeneric.dev/docs/reference/providers/error/raise_from), [`ReturnError`](https://contextgeneric.dev/docs/reference/providers/error/return_error), [`RaiseInfallible`](https://contextgeneric.dev/docs/reference/providers/error/raise_infallible), [`PanicOnError`](https://contextgeneric.dev/docs/reference/providers/error/panic_on_error), [`DiscardDetail`](https://contextgeneric.dev/docs/reference/providers/error/discard_detail), [`DebugError`](https://contextgeneric.dev/docs/reference/providers/error/debug_error), and [`DisplayError`](https://contextgeneric.dev/docs/reference/providers/error/display_error).
 
 #[cfg(feature = "alloc")]
 extern crate alloc;

crates/extra/cgp-field-extra/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "CGP's optional-field layer, for a builder whose fields are set in any order."
 
 [dependencies]
 cgp-field       = { workspace = true }

crates/extra/cgp-field-extra/src/lib.rs

@@ -1,3 +1,6 @@
 #![no_std]
+//! This crate provides CGP's optional-field layer, for a builder whose fields are set in any order.
+//!
+//! See [`HasOptionalBuilder`](https://contextgeneric.dev/docs/reference/traits/optional/has_optional_builder), [`ToOptional`](https://contextgeneric.dev/docs/reference/traits/optional/to_optional), [`SetOptional`](https://contextgeneric.dev/docs/reference/traits/optional/set_optional), and [`FinalizeOptional`](https://contextgeneric.dev/docs/reference/traits/optional/finalize_optional).
 
 pub mod impls;

crates/extra/cgp-handler/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "CGP's handler family: the computation components and the combinators that compose them."
 
 [dependencies]
 cgp         = { version = "0.8.0-alpha", path = "../../main/cgp-core", package = "cgp-core" }

crates/extra/cgp-handler/src/lib.rs

@@ -1,4 +1,8 @@
 #![no_std]
+//! This crate provides CGP's handler family: the computation components and the combinators that
+//! compose them.
+//!
+//! See [`CanCompute`](https://contextgeneric.dev/docs/reference/components/handler/computer), [`CanHandle`](https://contextgeneric.dev/docs/reference/components/handler/handler), [`PipeHandlers`](https://contextgeneric.dev/docs/reference/providers/handler/pipe_handlers), and [`Promote`](https://contextgeneric.dev/docs/reference/providers/handler/promote).
 
 mod components;
 mod providers;

crates/extra/cgp-monad/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "CGP's monadic handlers, which compose handlers through a monad."
 
 [dependencies]
 cgp         = { version = "0.8.0-alpha", path = "../../main/cgp-core", package = "cgp-core" }

crates/extra/cgp-monad/src/lib.rs

@@ -1,4 +1,7 @@
 #![no_std]
+//! This crate provides CGP's monadic handlers, which compose handlers through a monad.
+//!
+//! See [`MonadicBind`](https://contextgeneric.dev/docs/reference/traits/monad/monadic_bind), [`ContainsValue`](https://contextgeneric.dev/docs/reference/traits/monad/contains_value), [`LiftValue`](https://contextgeneric.dev/docs/reference/traits/monad/lift_value), and [`PipeMonadic`](https://contextgeneric.dev/docs/reference/providers/monad/pipe_monadic).
 
 pub mod monadic;
 pub mod providers;

crates/extra/cgp-run/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "CGP's task runners, which run a task named by a type-level code."
 
 [dependencies]
 cgp         = { version = "0.8.0-alpha", path = "../../main/cgp-core", package = "cgp-core" }

crates/extra/cgp-run/src/lib.rs

@@ -1,4 +1,7 @@
 #![no_std]
+//! This crate provides CGP's task runners, which run a task named by a type-level code.
+//!
+//! See [`CanRun`](https://contextgeneric.dev/docs/reference/components/runner) and [`CanSendRun`](https://contextgeneric.dev/docs/reference/components/send_runner).
 
 use core::future::Future;
 use core::marker::PhantomData;

crates/extra/cgp-runtime/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "CGP's runtime abstraction, which lets a context choose its async runtime."
 
 [dependencies]
 cgp   = { version = "0.8.0-alpha", path = "../../main/cgp-core", package = "cgp-core" }

crates/extra/cgp-runtime/src/lib.rs

@@ -1,3 +1,7 @@
+//! This crate provides CGP's runtime abstraction, which lets a context choose its async runtime.
+//!
+//! See [`HasRuntime`](https://contextgeneric.dev/docs/reference/components/has_runtime) and [`HasRuntimeType`](https://contextgeneric.dev/docs/reference/components/has_runtime_type).
+
 mod traits;
 
 pub use traits::{

crates/macros/cgp-async-macro/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "CGP's #[async_trait] macro, which rewrites a trait's async fn to return impl Future."
 
 [lib]
 proc-macro = true

crates/macros/cgp-async-macro/src/lib.rs

@@ -1,8 +1,8 @@
 #![no_std]
-
-/*!
-   This library provides helper macros for using async functions in traits.
-*/
+//! This crate provides CGP's `#[async_trait]` macro, which rewrites a trait's `async fn` to return
+//! `impl Future`.
+//!
+//! See [`#[async_trait]`](https://contextgeneric.dev/docs/reference/macros/async_trait).
 
 extern crate alloc;
 extern crate proc_macro;

crates/macros/cgp-macro-core/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "The shared core of CGP's procedural macros: the AST types, parsers, visitors, and code-generation helpers the macro crates build on."
 
 [dependencies]
 syn                 = { version = "2.0.95", features = [ "full", "extra-traits", "visit", "visit-mut" ] }

crates/macros/cgp-macro-core/src/lib.rs

@@ -1,3 +1,8 @@
+//! This crate holds the shared core of CGP's procedural macros: the AST types, parsers, visitors,
+//! and code-generation helpers the macro crates build on.
+//!
+//! See [`#[cgp_component]`](https://contextgeneric.dev/docs/reference/macros/cgp_component) and [`#[cgp_impl]`](https://contextgeneric.dev/docs/reference/macros/cgp_impl) for the macros it builds.
+
 pub mod exports;
 pub mod functions;
 pub mod macros;

crates/macros/cgp-macro-core/src/types/cgp_component/args/raw.rs

@@ -5,7 +5,7 @@ use syn::{Error, Ident};
 use crate::types::ident::IdentWithTypeGenerics;
 
 /// The attribute args exactly as written, before defaults are applied. Parses
-/// either a bare provider identifier or the `key: value` form; [`CgpComponentArgs`]
+/// either a bare provider identifier or the `key: value` form; [`CgpComponentArgs`](crate::types::cgp_component::CgpComponentArgs)
 /// resolves the defaults via `TryFrom`.
 #[derive(Default)]
 pub struct CgpComponentRawArgs {

crates/macros/cgp-macro-extra-core/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "The shared core of CGP's extra procedural macros: their AST types, parsers, and visitors."
 
 [dependencies]
 cgp-macro-core  = { workspace = true }

crates/macros/cgp-macro-extra-core/src/lib.rs

@@ -1,3 +1,8 @@
+//! This crate holds the shared core of CGP's extra procedural macros: their AST types, parsers, and
+//! visitors.
+//!
+//! See [`#[cgp_computer]`](https://contextgeneric.dev/docs/reference/macros/cgp_computer) and [`#[cgp_auto_dispatch]`](https://contextgeneric.dev/docs/reference/macros/cgp_auto_dispatch) for the macros it builds.
+
 pub mod exports;
 pub mod functions;
 pub mod types;

crates/macros/cgp-macro-extra-lib/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "The implementation of CGP's extra procedural macros, which lower through cgp-macro-core's AST types."
 
 [dependencies]
 cgp-macro-core          = { workspace = true }

crates/macros/cgp-macro-extra-lib/src/lib.rs

@@ -1,3 +1,8 @@
+//! This crate implements CGP's extra procedural macros, which lower through `cgp-macro-core`'s AST
+//! types.
+//!
+//! See [`#[cgp_computer]`](https://contextgeneric.dev/docs/reference/macros/cgp_computer), [`#[cgp_producer]`](https://contextgeneric.dev/docs/reference/macros/cgp_producer), and [`#[cgp_auto_dispatch]`](https://contextgeneric.dev/docs/reference/macros/cgp_auto_dispatch).
+
 mod cgp_auto_dispatch;
 mod cgp_computer;
 mod cgp_producer;

crates/macros/cgp-macro-extra/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "CGP's extra procedural macros, which define handler providers from functions and dispatch a trait over an enum."
 
 [lib]
 proc-macro = true

crates/macros/cgp-macro-extra/src/lib.rs

@@ -1,11 +1,8 @@
 #![no_std]
-
-/*!
-   This crate provides the proc macros that define handler providers from
-   functions, `#[cgp_computer]` and `#[cgp_producer]`, and the
-   `#[cgp_auto_dispatch]` macro that extends a per-type trait to extensible
-   enums. Each one forwards to `cgp-macro-extra-lib`.
-*/
+//! This crate provides CGP's extra procedural macros, which define handler providers from functions
+//! and dispatch a trait over an enum.
+//!
+//! See [`#[cgp_computer]`](https://contextgeneric.dev/docs/reference/macros/cgp_computer), [`#[cgp_producer]`](https://contextgeneric.dev/docs/reference/macros/cgp_producer), and [`#[cgp_auto_dispatch]`](https://contextgeneric.dev/docs/reference/macros/cgp_auto_dispatch).
 
 use proc_macro::TokenStream;
 

crates/macros/cgp-macro-lib/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "The implementation of CGP's procedural macros, one module per macro."
 
 [dependencies]
 cgp-macro-core  = { workspace = true }

crates/macros/cgp-macro-lib/src/lib.rs

@@ -1,3 +1,7 @@
+//! This crate implements CGP's procedural macros, one module per macro.
+//!
+//! See [`#[cgp_component]`](https://contextgeneric.dev/docs/reference/macros/cgp_component), [`#[cgp_impl]`](https://contextgeneric.dev/docs/reference/macros/cgp_impl), and [`delegate_components!`](https://contextgeneric.dev/docs/reference/macros/delegate_components).
+
 mod blanket_trait;
 mod cgp_auto_getter;
 mod cgp_component;

crates/macros/cgp-macro-test-util-lib/Cargo.toml

@@ -9,7 +9,7 @@ rust-version = { workspace = true }
 homepage     = { workspace = true }
 keywords     = { workspace = true }
 categories   = { workspace = true }
-description  = { workspace = true }
+description  = "The implementation of CGP's snapshot-testing macros."
 
 [dependencies]
 cgp-macro-lib       = { workspace = true }

crates/macros/cgp-macro-test-util-lib/src/lib.rs

@@ -1,3 +1,5 @@
+//! This crate implements CGP's snapshot-testing macros.
+
 pub mod entrypoints;
 pub mod functions;
 pub mod keywords;