diff --git a/README.md b/README.md index ece5f6934..b755b1caa 100644 --- a/README.md +++ b/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 diff --git a/crates/core/cgp-base-types/Cargo.toml b/crates/core/cgp-base-types/Cargo.toml index 8d8428e03..e38293062 100644 --- a/crates/core/cgp-base-types/Cargo.toml +++ b/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] diff --git a/crates/core/cgp-base-types/src/lib.rs b/crates/core/cgp-base-types/src/lib.rs index 592301f5c..1d8493381 100644 --- a/crates/core/cgp-base-types/src/lib.rs +++ b/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; diff --git a/crates/core/cgp-base-types/src/types/cons.rs b/crates/core/cgp-base-types/src/types/cons.rs index 92543c28c..052916706 100644 --- a/crates/core/cgp-base-types/src/types/cons.rs +++ b/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 diff --git a/crates/core/cgp-base-types/src/types/nil.rs b/crates/core/cgp-base-types/src/types/nil.rs index a132ba41d..ef5af5228 100644 --- a/crates/core/cgp-base-types/src/types/nil.rs +++ b/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; diff --git a/crates/core/cgp-component/Cargo.toml b/crates/core/cgp-component/Cargo.toml index ac6546a68..4acfe7a1a 100644 --- a/crates/core/cgp-component/Cargo.toml +++ b/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] diff --git a/crates/core/cgp-component/src/lib.rs b/crates/core/cgp-component/src/lib.rs index b63ed46a7..f29609fed 100644 --- a/crates/core/cgp-component/src/lib.rs +++ b/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; diff --git a/crates/core/cgp-error/Cargo.toml b/crates/core/cgp-error/Cargo.toml index d35418b49..99d588306 100644 --- a/crates/core/cgp-error/Cargo.toml +++ b/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" } diff --git a/crates/core/cgp-error/src/lib.rs b/crates/core/cgp-error/src/lib.rs index 56a70f70c..2a16e422b 100644 --- a/crates/core/cgp-error/src/lib.rs +++ b/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; diff --git a/crates/core/cgp-field/Cargo.toml b/crates/core/cgp-field/Cargo.toml index c7b6782eb..63745d37b 100644 --- a/crates/core/cgp-field/Cargo.toml +++ b/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 } diff --git a/crates/core/cgp-field/src/lib.rs b/crates/core/cgp-field/src/lib.rs index e4988ac94..7e9913326 100644 --- a/crates/core/cgp-field/src/lib.rs +++ b/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; diff --git a/crates/core/cgp-type/Cargo.toml b/crates/core/cgp-type/Cargo.toml index 1debbc201..6e74fa673 100644 --- a/crates/core/cgp-type/Cargo.toml +++ b/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" } diff --git a/crates/core/cgp-type/src/lib.rs b/crates/core/cgp-type/src/lib.rs index da84285c2..e23b61ab1 100644 --- a/crates/core/cgp-type/src/lib.rs +++ b/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; diff --git a/crates/extra/cgp-dispatch/Cargo.toml b/crates/extra/cgp-dispatch/Cargo.toml index 890f3be37..d22713ea5 100644 --- a/crates/extra/cgp-dispatch/Cargo.toml +++ b/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" } diff --git a/crates/extra/cgp-dispatch/src/lib.rs b/crates/extra/cgp-dispatch/src/lib.rs index 6568ec824..794d51ce2 100644 --- a/crates/extra/cgp-dispatch/src/lib.rs +++ b/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; diff --git a/crates/extra/cgp-error-extra/Cargo.toml b/crates/extra/cgp-error-extra/Cargo.toml index 0a7dd9478..9b8b324d4 100644 --- a/crates/extra/cgp-error-extra/Cargo.toml +++ b/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" ] diff --git a/crates/extra/cgp-error-extra/src/lib.rs b/crates/extra/cgp-error-extra/src/lib.rs index 5cefbc58d..c4d515019 100644 --- a/crates/extra/cgp-error-extra/src/lib.rs +++ b/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; diff --git a/crates/extra/cgp-field-extra/Cargo.toml b/crates/extra/cgp-field-extra/Cargo.toml index 63d3ab114..ea7457935 100644 --- a/crates/extra/cgp-field-extra/Cargo.toml +++ b/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 } diff --git a/crates/extra/cgp-field-extra/src/lib.rs b/crates/extra/cgp-field-extra/src/lib.rs index f092d7fee..d7dd33457 100644 --- a/crates/extra/cgp-field-extra/src/lib.rs +++ b/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; diff --git a/crates/extra/cgp-handler/Cargo.toml b/crates/extra/cgp-handler/Cargo.toml index 996aac6af..448a249c2 100644 --- a/crates/extra/cgp-handler/Cargo.toml +++ b/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" } diff --git a/crates/extra/cgp-handler/src/lib.rs b/crates/extra/cgp-handler/src/lib.rs index 727fc336b..873c98946 100644 --- a/crates/extra/cgp-handler/src/lib.rs +++ b/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; diff --git a/crates/extra/cgp-monad/Cargo.toml b/crates/extra/cgp-monad/Cargo.toml index 6bc246afa..f7d6d9570 100644 --- a/crates/extra/cgp-monad/Cargo.toml +++ b/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" } diff --git a/crates/extra/cgp-monad/src/lib.rs b/crates/extra/cgp-monad/src/lib.rs index d25570085..4c77d7e38 100644 --- a/crates/extra/cgp-monad/src/lib.rs +++ b/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; diff --git a/crates/extra/cgp-run/Cargo.toml b/crates/extra/cgp-run/Cargo.toml index 599ded25f..de24ffcff 100644 --- a/crates/extra/cgp-run/Cargo.toml +++ b/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" } diff --git a/crates/extra/cgp-run/src/lib.rs b/crates/extra/cgp-run/src/lib.rs index 4ba74646c..5d563b679 100644 --- a/crates/extra/cgp-run/src/lib.rs +++ b/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; diff --git a/crates/extra/cgp-runtime/Cargo.toml b/crates/extra/cgp-runtime/Cargo.toml index 1af1a45f7..d404acad5 100644 --- a/crates/extra/cgp-runtime/Cargo.toml +++ b/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" } diff --git a/crates/extra/cgp-runtime/src/lib.rs b/crates/extra/cgp-runtime/src/lib.rs index 834ee4754..3134ef943 100644 --- a/crates/extra/cgp-runtime/src/lib.rs +++ b/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::{ diff --git a/crates/macros/cgp-async-macro/Cargo.toml b/crates/macros/cgp-async-macro/Cargo.toml index 20331cdb0..3abac3658 100644 --- a/crates/macros/cgp-async-macro/Cargo.toml +++ b/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 diff --git a/crates/macros/cgp-async-macro/src/lib.rs b/crates/macros/cgp-async-macro/src/lib.rs index 6db629de7..4f57818e4 100644 --- a/crates/macros/cgp-async-macro/src/lib.rs +++ b/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; diff --git a/crates/macros/cgp-macro-core/Cargo.toml b/crates/macros/cgp-macro-core/Cargo.toml index 0a993aa3e..d42f91efd 100644 --- a/crates/macros/cgp-macro-core/Cargo.toml +++ b/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" ] } diff --git a/crates/macros/cgp-macro-core/src/lib.rs b/crates/macros/cgp-macro-core/src/lib.rs index 694d75184..7295e2765 100644 --- a/crates/macros/cgp-macro-core/src/lib.rs +++ b/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; diff --git a/crates/macros/cgp-macro-core/src/types/cgp_component/args/raw.rs b/crates/macros/cgp-macro-core/src/types/cgp_component/args/raw.rs index 4f44c9b11..b2260f18a 100644 --- a/crates/macros/cgp-macro-core/src/types/cgp_component/args/raw.rs +++ b/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 { diff --git a/crates/macros/cgp-macro-extra-core/Cargo.toml b/crates/macros/cgp-macro-extra-core/Cargo.toml index def7fb7cc..0db917742 100644 --- a/crates/macros/cgp-macro-extra-core/Cargo.toml +++ b/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 } diff --git a/crates/macros/cgp-macro-extra-core/src/lib.rs b/crates/macros/cgp-macro-extra-core/src/lib.rs index 59e1bcb29..f9a7d9b42 100644 --- a/crates/macros/cgp-macro-extra-core/src/lib.rs +++ b/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; diff --git a/crates/macros/cgp-macro-extra-lib/Cargo.toml b/crates/macros/cgp-macro-extra-lib/Cargo.toml index a463b64ae..d0307e38b 100644 --- a/crates/macros/cgp-macro-extra-lib/Cargo.toml +++ b/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 } diff --git a/crates/macros/cgp-macro-extra-lib/src/lib.rs b/crates/macros/cgp-macro-extra-lib/src/lib.rs index 5bc532c3a..002e81f26 100644 --- a/crates/macros/cgp-macro-extra-lib/src/lib.rs +++ b/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; diff --git a/crates/macros/cgp-macro-extra/Cargo.toml b/crates/macros/cgp-macro-extra/Cargo.toml index 6d49f7b7f..cb05b31ca 100644 --- a/crates/macros/cgp-macro-extra/Cargo.toml +++ b/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 diff --git a/crates/macros/cgp-macro-extra/src/lib.rs b/crates/macros/cgp-macro-extra/src/lib.rs index 72adb4c87..739ca8fdc 100644 --- a/crates/macros/cgp-macro-extra/src/lib.rs +++ b/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; diff --git a/crates/macros/cgp-macro-lib/Cargo.toml b/crates/macros/cgp-macro-lib/Cargo.toml index 7bd7a4aae..573e96991 100644 --- a/crates/macros/cgp-macro-lib/Cargo.toml +++ b/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 } diff --git a/crates/macros/cgp-macro-lib/src/lib.rs b/crates/macros/cgp-macro-lib/src/lib.rs index 0b44d2b4c..318c6e166 100644 --- a/crates/macros/cgp-macro-lib/src/lib.rs +++ b/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; diff --git a/crates/macros/cgp-macro-test-util-lib/Cargo.toml b/crates/macros/cgp-macro-test-util-lib/Cargo.toml index 71d9e1b36..d613aa199 100644 --- a/crates/macros/cgp-macro-test-util-lib/Cargo.toml +++ b/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 } diff --git a/crates/macros/cgp-macro-test-util-lib/src/lib.rs b/crates/macros/cgp-macro-test-util-lib/src/lib.rs index a7817a6a8..287ff3c7c 100644 --- a/crates/macros/cgp-macro-test-util-lib/src/lib.rs +++ b/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; diff --git a/crates/macros/cgp-macro-test-util/Cargo.toml b/crates/macros/cgp-macro-test-util/Cargo.toml index d17deae3b..71c01a0d6 100644 --- a/crates/macros/cgp-macro-test-util/Cargo.toml +++ b/crates/macros/cgp-macro-test-util/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 snapshot-testing macros, which emit the real generated code and pin it as an inline insta snapshot." [lib] proc-macro = true diff --git a/crates/macros/cgp-macro-test-util/src/lib.rs b/crates/macros/cgp-macro-test-util/src/lib.rs index 0f037e9bd..74ae91076 100644 --- a/crates/macros/cgp-macro-test-util/src/lib.rs +++ b/crates/macros/cgp-macro-test-util/src/lib.rs @@ -1,3 +1,6 @@ +//! This crate provides CGP's snapshot-testing macros, which emit the real generated code and pin it +//! as an inline `insta` snapshot. + use cgp_macro_test_util_lib::entrypoints; use proc_macro::TokenStream; diff --git a/crates/macros/cgp-macro/Cargo.toml b/crates/macros/cgp-macro/Cargo.toml index 414b52f36..aa0e80b31 100644 --- a/crates/macros/cgp-macro/Cargo.toml +++ b/crates/macros/cgp-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 procedural macros, from defining a component to wiring and checking a context." [lib] proc-macro = true diff --git a/crates/macros/cgp-macro/src/lib.rs b/crates/macros/cgp-macro/src/lib.rs index b13d75107..52e7e80b0 100644 --- a/crates/macros/cgp-macro/src/lib.rs +++ b/crates/macros/cgp-macro/src/lib.rs @@ -1,8 +1,8 @@ #![no_std] - -/*! - This crate provides the proc macros used for defining CGP components. -*/ +//! This crate provides CGP's procedural macros, from defining a component to wiring and checking a +//! context. +//! +//! See [`#[cgp_component]`](https://contextgeneric.dev/docs/reference/macros/cgp_component), [`#[cgp_impl]`](https://contextgeneric.dev/docs/reference/macros/cgp_impl), [`delegate_components!`](https://contextgeneric.dev/docs/reference/macros/delegate_components), and [`check_components!`](https://contextgeneric.dev/docs/reference/macros/check_components). use proc_macro::TokenStream; diff --git a/crates/main/cgp-base-extra/Cargo.toml b/crates/main/cgp-base-extra/Cargo.toml index 3dbdd7974..a9dbdcc71 100644 --- a/crates/main/cgp-base-extra/Cargo.toml +++ b/crates/main/cgp-base-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 base layer with the abstract-type layer added." [dependencies] cgp-base = { workspace = true } diff --git a/crates/main/cgp-base-extra/src/lib.rs b/crates/main/cgp-base-extra/src/lib.rs index ffdda3d0c..764137168 100644 --- a/crates/main/cgp-base-extra/src/lib.rs +++ b/crates/main/cgp-base-extra/src/lib.rs @@ -1,4 +1,7 @@ #![no_std] +//! This crate re-exports CGP's base layer with the abstract-type layer added. +//! +//! See [`HasType`](https://contextgeneric.dev/docs/reference/components/has_type). pub mod macro_prelude; diff --git a/crates/main/cgp-base/Cargo.toml b/crates/main/cgp-base/Cargo.toml index 1ecf3dbab..522142bc3 100644 --- a/crates/main/cgp-base/Cargo.toml +++ b/crates/main/cgp-base/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 base layer: the type-level primitives, the component machinery, and the macros." [dependencies] cgp-base-types = { workspace = true } diff --git a/crates/main/cgp-base/src/lib.rs b/crates/main/cgp-base/src/lib.rs index c0e3c4946..dd67a7949 100644 --- a/crates/main/cgp-base/src/lib.rs +++ b/crates/main/cgp-base/src/lib.rs @@ -1,3 +1,8 @@ +//! This crate re-exports CGP's base layer: the type-level primitives, the component machinery, and +//! the macros. +//! +//! See [`#[cgp_component]`](https://contextgeneric.dev/docs/reference/macros/cgp_component), [`Symbol!`](https://contextgeneric.dev/docs/reference/macros/symbol), and [`Cons`](https://contextgeneric.dev/docs/reference/types/cons). + pub mod macro_prelude; pub use cgp_base_types::*; diff --git a/crates/main/cgp-core/Cargo.toml b/crates/main/cgp-core/Cargo.toml index a4ba1e8f2..94644a9ca 100644 --- a/crates/main/cgp-core/Cargo.toml +++ b/crates/main/cgp-core/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 core layer through cgp::core: the base layer, the macros, the async trait macro, and the error, field, and type components." [dependencies] cgp-base = { workspace = true } diff --git a/crates/main/cgp-core/src/lib.rs b/crates/main/cgp-core/src/lib.rs index f94af85eb..8fa7228b4 100644 --- a/crates/main/cgp-core/src/lib.rs +++ b/crates/main/cgp-core/src/lib.rs @@ -1,5 +1,9 @@ #![no_std] #![allow(mixed_script_confusables)] +//! This crate re-exports CGP's core layer through `cgp::core`: the base layer, the macros, the +//! async trait macro, and the error, field, and type components. +//! +//! See [`#[cgp_component]`](https://contextgeneric.dev/docs/reference/macros/cgp_component), [`HasField`](https://contextgeneric.dev/docs/reference/traits/field-access/has_field), and [`HasErrorType`](https://contextgeneric.dev/docs/reference/components/has_error_type). pub mod prelude; diff --git a/crates/main/cgp-extra/Cargo.toml b/crates/main/cgp-extra/Cargo.toml index 71c5c6d58..40608e5eb 100644 --- a/crates/main/cgp-extra/Cargo.toml +++ b/crates/main/cgp-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 layer through cgp::extra: handlers, monads, dispatch, runtime, runners, the optional-field layer, and the generic error providers." [features] default = [ "full" ] diff --git a/crates/main/cgp-extra/src/lib.rs b/crates/main/cgp-extra/src/lib.rs index a345812fc..b13e7834a 100644 --- a/crates/main/cgp-extra/src/lib.rs +++ b/crates/main/cgp-extra/src/lib.rs @@ -1,4 +1,8 @@ #![no_std] +//! This crate re-exports CGP's extra layer through `cgp::extra`: handlers, monads, dispatch, +//! runtime, runners, the optional-field layer, and the generic error providers. +//! +//! See [`CanHandle`](https://contextgeneric.dev/docs/reference/components/handler/handler), [`PipeHandlers`](https://contextgeneric.dev/docs/reference/providers/handler/pipe_handlers), and [`RaiseFrom`](https://contextgeneric.dev/docs/reference/providers/error/raise_from). pub mod prelude;