instances docs

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.

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>(U, V);

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.

src/func/instances/future.rs

@@ -1,7 +1,9 @@
 //! Async [Monad] based on [`Pin<Box<dyn Future>>`] (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;

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;

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<A, E>`] alternative see [`super::result`]
+//! For [`Result<A, E>`] alternative see [`result`].
+//!
+//! For values that are never [`None`], see [`solo`].
 
+#[cfg(doc)]
+use crate::func::instances::*;
 use crate::func::*;
 
 #[derive(SharedFunctorAny)]

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>(T, O);
@@ -133,18 +141,17 @@ pub struct DeriveFail<Ex>(Ex);
 
 impl<Ex> DeriveMonad for DeriveFail<Ex> {}
 
-impl<'a, E: 'a, Ex: 'a, T: MonadFail<'a, Result<E, Ex>>> Fail<'a, E>
-    for OverloadInstance<T, DeriveFail<Ex>>
-{
+impl<'a, E: 'a, Ex: 'a, T: MonadFail<'a, Result<E, Ex>>> Fail<'a, E> for EmbedFail<T, Ex> {
     fn fail<A: 'a>(e: E) -> Self::F<A> {
         T::fail(Ok(e))
     }
 }
 
-struct DeriveFailAny<Ex, Fallible>(Ex, Fallible);
+/// Instance of [`MonadFailAny`] for [`EmbedFail`].
+pub struct DeriveFailAny<Ex, Fallible>(Ex, Fallible);
 
 impl<'a, Ex: 'a, Fallible: MonadFailAny<'a>> MonadFailAny<'a> for DeriveFailAny<Ex, Fallible> {
-    type W<E: 'a> = OverloadInstance<Fallible::W<Result<E, Ex>>, DeriveFail<Ex>>;
+    type W<E: 'a> = EmbedFail<Fallible::W<Result<E, Ex>>, Ex>;
 
     type T = Fallible::W<Ex>;
 
@@ -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<T, Ex> = OverloadInstance<T, DeriveFail<Ex>>;

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<A>`] alternative see [`super::option`]
+//! For [`Option<A>`] alternative see [`option`].
+//!
+//! For values that are never [`Err`], see [`solo`].
 
+#[cfg(doc)]
+use crate::func::instances::*;
 use crate::func::*;
 
 #[derive(SharedFunctorAny)]

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)]

src/func/instances/stackless.rs

@@ -1,11 +1,13 @@
 //! Helper [Monad]s to move deep execution chains off the stack onto the heap.
 //! [`Stackless<A>`] 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> {

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>(E);