diff --git a/src/func/instances.rs b/src/func/instances.rs index 3eb2c52..6169f7c 100644 --- a/src/func/instances.rs +++ b/src/func/instances.rs @@ -11,9 +11,11 @@ //! For "creative" execution models, see [`lazy`][^research] and [`stackless`][^research]. //! //! For combining monads, see [`composition`][^research]. -//! +//! //! For adding extra metadata to values, see [`effect`][^research]. //! +//! For extending existing instances, see [`overload`][^research]. +//! //! [^production]: instances expected to be used in production. //! //! [^research]: instances used for research purposes to enhance the abstract interfaces. diff --git a/src/func/instances/composition.rs b/src/func/instances/composition.rs index fdf9a66..7279cc4 100644 --- a/src/func/instances/composition.rs +++ b/src/func/instances/composition.rs @@ -1,5 +1,11 @@ //! [Functor]s derived on compositions of other [Functor]s. +//! +//! For changing behaviour of existing [instances], see [`overload`]. +//! +//! For [`future`]-[`result`] composition, see [`tryfuture`]. +#[cfg(doc)] +use crate::func::instances::*; use crate::func::*; pub struct CompositionInstance(U, V); diff --git a/src/func/instances/effect.rs b/src/func/instances/effect.rs index d4ef2db..70b1857 100644 --- a/src/func/instances/effect.rs +++ b/src/func/instances/effect.rs @@ -1,5 +1,11 @@ //! [Monad] for passing and combining metadata related to the evaluation of values. +//! +//! For "either"/"sum" wrapping, see [`result`]. +//! +//! For no extra data, see [`solo`]. +#[cfg(doc)] +use crate::func::instances::*; use crate::func::*; /// Metadata type. diff --git a/src/func/instances/future.rs b/src/func/instances/future.rs index 2397702..7275c7d 100644 --- a/src/func/instances/future.rs +++ b/src/func/instances/future.rs @@ -1,7 +1,9 @@ //! Async [Monad] based on [`Pin>`] (see: [`Pin`], [`Box::pin`], [`Future`]). //! This generally allows just using `.await` on wrapped instances. //! -//! For sync, see [`super::solo`]. +//! For sync, see [`solo`]. +//! +//! For fallible futures, see [`tryfuture`]. use std::{future::Future, pin::Pin}; @@ -10,6 +12,8 @@ use futures::{ join, FutureExt, }; +#[cfg(doc)] +use crate::func::instances::*; use crate::func::*; pub struct FutureInstance; diff --git a/src/func/instances/lazy.rs b/src/func/instances/lazy.rs index 35b7cc1..9ef13a0 100644 --- a/src/func/instances/lazy.rs +++ b/src/func/instances/lazy.rs @@ -5,10 +5,12 @@ //! [`LazyInstance::replace`] and [`LazyInstance::discard_first`]/[`LazyInstance::discard_second`] //! actually fully cancel the "unnecessary" computation. //! -//! For stackless execution see [`super::stackless`]. +//! For stackless execution see [`stackless`]. use std::{cell::RefCell, rc::Rc}; +#[cfg(doc)] +use crate::func::instances::*; use crate::func::*; pub struct LazyInstance; diff --git a/src/func/instances/option.rs b/src/func/instances/option.rs index cc8d5ba..37f4924 100644 --- a/src/func/instances/option.rs +++ b/src/func/instances/option.rs @@ -5,8 +5,12 @@ //! [`OptionInstance::replace`] and [`OptionInstance::discard_first`]/[`OptionInstance::discard_second`], //! even if the value of the option would be ignored. //! -//! For [`Result`] alternative see [`super::result`] +//! For [`Result`] alternative see [`result`]. +//! +//! For values that are never [`None`], see [`solo`]. +#[cfg(doc)] +use crate::func::instances::*; use crate::func::*; #[derive(SharedFunctorAny)] diff --git a/src/func/instances/overload.rs b/src/func/instances/overload.rs index 1545067..0690ee0 100644 --- a/src/func/instances/overload.rs +++ b/src/func/instances/overload.rs @@ -1,5 +1,13 @@ +//! Add extra behaviour on top of an existing instance. +//! +//! Initially made as [`EmbedFail`] implementation detail. +//! +//! For combining existing [instances], see [`composition`]. + use std::marker::PhantomData; +#[cfg(doc)] +use crate::func::instances::*; use crate::func::*; pub struct OverloadInstance(T, O); @@ -133,18 +141,17 @@ pub struct DeriveFail(Ex); impl DeriveMonad for DeriveFail {} -impl<'a, E: 'a, Ex: 'a, T: MonadFail<'a, Result>> Fail<'a, E> - for OverloadInstance> -{ +impl<'a, E: 'a, Ex: 'a, T: MonadFail<'a, Result>> Fail<'a, E> for EmbedFail { fn fail(e: E) -> Self::F { T::fail(Ok(e)) } } -struct DeriveFailAny(Ex, Fallible); +/// Instance of [`MonadFailAny`] for [`EmbedFail`]. +pub struct DeriveFailAny(Ex, Fallible); impl<'a, Ex: 'a, Fallible: MonadFailAny<'a>> MonadFailAny<'a> for DeriveFailAny { - type W = OverloadInstance>, DeriveFail>; + type W = EmbedFail>, Ex>; type T = Fallible::W; @@ -206,4 +213,5 @@ impl<'a, T: SharedFunctor<'a>, O: 'a + DeriveWeakFunctor> SharedFunctor<'a> } } +/// [`MonadFail`] based on embedding the error into some other [`MonadFailAny`]. pub type EmbedFail = OverloadInstance>; diff --git a/src/func/instances/result.rs b/src/func/instances/result.rs index e8a45a9..7ecf923 100644 --- a/src/func/instances/result.rs +++ b/src/func/instances/result.rs @@ -5,8 +5,12 @@ //! [`ResultInstance::replace`] and [`ResultInstance::discard_first`]/[`ResultInstance::discard_second`], //! even if the value of the option would be ignored. //! -//! For [`Option`] alternative see [`super::option`] +//! For [`Option`] alternative see [`option`]. +//! +//! For values that are never [`Err`], see [`solo`]. +#[cfg(doc)] +use crate::func::instances::*; use crate::func::*; #[derive(SharedFunctorAny)] diff --git a/src/func/instances/solo.rs b/src/func/instances/solo.rs index 185d19a..38f97e7 100644 --- a/src/func/instances/solo.rs +++ b/src/func/instances/solo.rs @@ -1,7 +1,11 @@ //! Simplest sync [Monad]. //! -//! For async, see [`super::future`]. +//! For async, see [`future`]. +//! +//! For abstracting away dealing with fallible data, see [`option`]/[`result`]. +#[cfg(doc)] +use crate::func::instances::*; use crate::func::*; #[derive(SharedFunctorAny)] diff --git a/src/func/instances/stackless.rs b/src/func/instances/stackless.rs index d8127ca..ffceb8a 100644 --- a/src/func/instances/stackless.rs +++ b/src/func/instances/stackless.rs @@ -1,11 +1,13 @@ //! Helper [Monad]s to move deep execution chains off the stack onto the heap. //! [`Stackless`] represents a wrapped value. //! -//! For lazy stackful execution see [`super::lazy`]. +//! For lazy stackful execution see [`lazy`]. use std::{cell::Cell, rc::Rc}; use crate::func::derivations::*; +#[cfg(doc)] +use crate::func::instances::*; use crate::func::*; enum EvalTree<'a> { diff --git a/src/func/instances/tryfuture.rs b/src/func/instances/tryfuture.rs index 7662582..2f479d7 100644 --- a/src/func/instances/tryfuture.rs +++ b/src/func/instances/tryfuture.rs @@ -1,3 +1,9 @@ +//! Fallible version of [`future`]. +//! +//! Preferred over building it out of [`composition`]. +//! +//! To embed extra errors, see [`overload::EmbedFail`]. + use std::{future::Future, pin::Pin}; use futures::{ @@ -5,6 +11,8 @@ use futures::{ try_join, FutureExt, }; +#[cfg(doc)] +use crate::func::instances::*; use crate::func::*; pub struct TryFutureInstance(E);