From a4fa5ac005591436393bdb889b69efcb5a4c6c71 Mon Sep 17 00:00:00 2001 From: Soares Chen Date: Sat, 7 Nov 2026 22:00:40 +0100 Subject: [PATCH] Document every published crate A crates.io or docs.rs visitor found an empty page for 25 of the 29 published crates, because only four included a README as their crate doc and the rest inherited one workspace description. Each crate now opens with a doc that states what it provides and links the reference page for its constructs, and each carries its own description. The docs build with warnings denied, which surfaced three broken intra-doc links in `cgp-macro-core` and `cgp-base-types`; those are fixed here too. --- README.md | 7 ++++--- crates/core/cgp-base-types/Cargo.toml | 2 +- crates/core/cgp-base-types/src/lib.rs | 4 ++++ crates/core/cgp-base-types/src/types/cons.rs | 2 +- crates/core/cgp-base-types/src/types/nil.rs | 4 ++-- crates/core/cgp-component/Cargo.toml | 2 +- crates/core/cgp-component/src/lib.rs | 9 ++++----- crates/core/cgp-error/Cargo.toml | 2 +- crates/core/cgp-error/src/lib.rs | 3 +++ crates/core/cgp-field/Cargo.toml | 2 +- crates/core/cgp-field/src/lib.rs | 4 ++++ crates/core/cgp-type/Cargo.toml | 2 +- crates/core/cgp-type/src/lib.rs | 3 +++ crates/extra/cgp-dispatch/Cargo.toml | 2 +- crates/extra/cgp-dispatch/src/lib.rs | 4 ++++ crates/extra/cgp-error-extra/Cargo.toml | 2 +- crates/extra/cgp-error-extra/src/lib.rs | 4 ++++ crates/extra/cgp-field-extra/Cargo.toml | 2 +- crates/extra/cgp-field-extra/src/lib.rs | 3 +++ crates/extra/cgp-handler/Cargo.toml | 2 +- crates/extra/cgp-handler/src/lib.rs | 4 ++++ crates/extra/cgp-monad/Cargo.toml | 2 +- crates/extra/cgp-monad/src/lib.rs | 3 +++ crates/extra/cgp-run/Cargo.toml | 2 +- crates/extra/cgp-run/src/lib.rs | 3 +++ crates/extra/cgp-runtime/Cargo.toml | 2 +- crates/extra/cgp-runtime/src/lib.rs | 4 ++++ crates/macros/cgp-async-macro/Cargo.toml | 2 +- crates/macros/cgp-async-macro/src/lib.rs | 8 ++++---- crates/macros/cgp-macro-core/Cargo.toml | 2 +- crates/macros/cgp-macro-core/src/lib.rs | 5 +++++ .../src/types/cgp_component/args/raw.rs | 2 +- crates/macros/cgp-macro-extra-core/Cargo.toml | 2 +- crates/macros/cgp-macro-extra-core/src/lib.rs | 5 +++++ crates/macros/cgp-macro-extra-lib/Cargo.toml | 2 +- crates/macros/cgp-macro-extra-lib/src/lib.rs | 5 +++++ crates/macros/cgp-macro-extra/Cargo.toml | 2 +- crates/macros/cgp-macro-extra/src/lib.rs | 11 ++++------- crates/macros/cgp-macro-lib/Cargo.toml | 2 +- crates/macros/cgp-macro-lib/src/lib.rs | 4 ++++ crates/macros/cgp-macro-test-util-lib/Cargo.toml | 2 +- crates/macros/cgp-macro-test-util-lib/src/lib.rs | 2 ++ crates/macros/cgp-macro-test-util/Cargo.toml | 2 +- crates/macros/cgp-macro-test-util/src/lib.rs | 3 +++ crates/macros/cgp-macro/Cargo.toml | 2 +- crates/macros/cgp-macro/src/lib.rs | 8 ++++---- crates/main/cgp-base-extra/Cargo.toml | 2 +- crates/main/cgp-base-extra/src/lib.rs | 3 +++ crates/main/cgp-base/Cargo.toml | 2 +- crates/main/cgp-base/src/lib.rs | 5 +++++ crates/main/cgp-core/Cargo.toml | 2 +- crates/main/cgp-core/src/lib.rs | 4 ++++ crates/main/cgp-extra/Cargo.toml | 2 +- crates/main/cgp-extra/src/lib.rs | 4 ++++ 54 files changed, 128 insertions(+), 52 deletions(-) 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;