Add some docs

Signed-off-by: Michael X. Grey <grey@openrobotics.org>

Author: mxgrey

src/callback.rs

@@ -40,8 +40,33 @@ use std::{
 /// instance. If the Callback has any internal state (e.g. [`Local`](bevy::prelude::Local)
 /// parameters, change trackers, or mutable captured variables), that internal state will
 /// be shared among all its clones.
-//
-// TODO(@mxgrey): Explain the different ways to instantiate a Callback.
+///
+/// There are three ways to instantiate a callback:
+///
+/// ### [`.as_callback()`](AsCallback)
+///
+/// If you have a Bevy system with an input parameter of `In<`[`AsyncCallback`]`>`
+/// or `In<`[`BlockingCallback`]`>` then you can convert it into a callback
+/// object by applying `.as_callback()`.
+///
+/// ### [`.into_async_callback()`](IntoAsyncCallback)
+///
+/// If you have a Bevy system whose return type implements the [`Future`] trait,
+/// it can be converted into an async callback object by applying
+/// `.into_async_callback()` to it. The `Response` type of the callback will be
+/// `Future::Output` rather than the return type of the system. The return value
+/// will be polled in an async compute task pool.
+///
+/// ### [`.into_blocking_callback()`](IntoBlockingCallback)
+///
+/// Any Bevy system can be converted into a blocking callback by applying
+/// `.into_blocking_callback()` to it. The `Request` type of the callback will
+/// be whatever the input type of the system is (the `T` inside of `In<T>`). The
+/// `Response` type of the callback will be whatever the return value of the
+/// callback is.
+///
+/// A blocking callback is always an exclusive system, so it will block all
+/// other systems from running until it is finished.
 pub struct Callback<Request, Response, Streams = ()> {
     pub(crate) inner: Arc<Mutex<InnerCallback<Request, Response, Streams>>>,
 }
@@ -326,6 +351,7 @@ where
     }
 }
 
+/// Use this to convert any Bevy system into a blocking callback.
 pub trait IntoBlockingCallback<M> {
     type Request;
     type Response;

src/chain.rs

@@ -127,8 +127,8 @@ impl<'w, 's, 'a, 'b, T: 'static + Send + Sync> Chain<'w, 's, 'a, 'b, T> {
         }
     }
 
-    /// Apply a one-time map whose input is a [`BlockingMap`](crate::BlockingMap)
-    /// or an [`AsyncMap`](crate::AsyncMap).
+    /// Apply a function whose input is [`BlockingMap<T>`](crate::BlockingMap)
+    /// or [`AsyncMap<T>`](crate::AsyncMap).
     #[must_use]
     pub fn map<M, F: AsMap<M>>(
         self,
@@ -156,7 +156,7 @@ impl<'w, 's, 'a, 'b, T: 'static + Send + Sync> Chain<'w, 's, 'a, 'b, T> {
         self.then_node(f.as_map())
     }
 
-    /// Apply a map whose input is the Response of the current Chain. The
+    /// Apply a function whose input is the Response of the current Chain. The
     /// output of the map will be the Response of the returned Chain.
     ///
     /// This takes in a regular blocking function rather than an async function,

src/lib.rs

@@ -85,28 +85,17 @@ pub mod testing;
 
 use bevy::prelude::{Entity, In};
 
-/// Use BlockingService to indicate that your system is a blocking service and
-/// to specify its input request type. For example:
+/// Use `BlockingService` to indicate that your system is a blocking [`Service`].
 ///
-/// ```
-/// use bevy::prelude::*;
-/// use bevy_impulse::*;
+/// A blocking service will have exclusive world access while it runs, which
+/// means no other system will be able to run simultaneously. Each service is
+/// associated with its own unique entity which can be used to store state or
+/// configuration parameters.
 ///
-/// #[derive(Component, Resource)]
-/// struct Precision(i32);
-///
-/// fn rounding_service(
-///     In(input): InBlockingService<f64>,
-///     global_precision: Res<Precision>,
-/// ) -> f64 {
-///     (input.request * 10_f64.powi(global_precision.0)).floor() * 10_f64.powi(-global_precision.0)
-/// }
-/// ```
-///
-/// The systems of more complex services might need to know what entity is
-/// providing the service, e.g. if the service provider is configured with
-/// additional components that need to be queried when a request comes in. For
-/// that you can check the `provider` field of `BlockingService`:
+/// Some services might need to know what entity is providing the service, e.g.
+/// if the service provider is configured with additional components that need
+/// to be queried when a request comes in. For that you can check the `provider`
+/// field of `BlockingService`:
 ///
 /// ```
 /// use bevy::prelude::*;
@@ -141,9 +130,9 @@ pub struct BlockingService<Request, Streams: StreamPack = ()> {
 /// Use this to reduce bracket noise when you need `In<BlockingService<R>>`.
 pub type InBlockingService<Request, Streams = ()> = In<BlockingService<Request, Streams>>;
 
-/// Use AsyncService to indicate that your system is an async service and to
-/// specify its input request type. Being async means it must return a
-/// `Future<Output=Response>` which will be processed by a task pool.
+/// Use AsyncService to indicate that your system is an async [`Service`]. Being
+/// async means it must return a [`Future<Output=Response>`](std::future::Future)
+/// which will be processed by a task pool.
 ///
 /// This comes with a [`Channel`] that allows your Future to interact with Bevy's
 /// ECS asynchronously while it is polled from inside the task pool.
@@ -169,6 +158,10 @@ pub type InAsyncService<Request, Streams = ()> = In<AsyncService<Request, Stream
 /// Use BlockingCallback to indicate that your system is meant to define a
 /// blocking [`Callback`]. Callbacks are different from services because they are
 /// not associated with any entity.
+///
+/// Alternatively any Bevy system with an input of `In<Request>` can be converted
+/// into a blocking callback by applying
+/// [`.into_blocking_callback()`](crate::IntoBlockingCallback).
 #[non_exhaustive]
 pub struct BlockingCallback<Request, Streams: StreamPack = ()> {
     /// The input data of the request
@@ -199,9 +192,9 @@ pub struct AsyncCallback<Request, Streams: StreamPack = ()> {
     pub session: Entity,
 }
 
-/// Use BlockingMap to indicate that your function is meant to define a blocking
-/// [`Map`]. A Map is not associated with any entity, and it cannot be a Bevy
-/// System. These limited traits allow them to be processed more efficiently.
+/// Use `BlockingMap`` to indicate that your function is a blocking map. A map
+/// is not associated with any entity, and it cannot be a Bevy System. These
+/// restrictions allow them to be processed more efficiently.
 #[non_exhaustive]
 pub struct BlockingMap<Request, Streams: StreamPack = ()> {
     /// The input data of the request
@@ -214,11 +207,11 @@ pub struct BlockingMap<Request, Streams: StreamPack = ()> {
     pub session: Entity,
 }
 
-/// Use AsyncMap to indicate that your function is meant to define an async
-/// [`Map`]. A Map is not associated with any entity, and it cannot be a Bevy
-/// System. These limited traits allow them to be processed more efficiently.
+/// Use AsyncMap to indicate that your function is an async map. A Map is not
+/// associated with any entity, and it cannot be a Bevy System. These
+/// restrictions allow them to be processed more efficiently.
 ///
-/// An async Map must return a [`Future<Output=Response>`](std::future::Future)
+/// An async map must return a [`Future<Output=Response>`](std::future::Future)
 /// that will be polled by the async task pool.
 #[non_exhaustive]
 pub struct AsyncMap<Request, Streams: StreamPack = ()> {