From 2ccfe4f39a6c83d7d8cc5152f19f49dd661b4a3e Mon Sep 17 00:00:00 2001
From: "Spencer C. Imbleau" <simbleau@blueorigin.com>
Date: Sat, 9 Sep 2023 17:55:54 -0400
Subject: [PATCH] docs: fix all links and enforce docs

---
 src/lib.rs         |  5 ++++-
 src/native/mod.rs  |  8 +++++---
 src/receiver.rs    |  3 ++-
 src/task_pool.rs   | 12 ++++++------
 src/task_runner.rs |  5 +++--
 src/wasm/mod.rs    |  8 ++++++--
 6 files changed, 26 insertions(+), 15 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 730eddf..f8370ee 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,6 @@
+#![deny(missing_docs)]
+//! Ergonomic abstractions to async programming in Bevy for all platforms.
+
 use cfg_if::cfg_if;
 
 mod receiver;
@@ -18,7 +21,7 @@ cfg_if! {
     }
 }
 
-/// The status of an [`AsyncTask`].
+/// A poll status for an [`AsyncTask`].
 pub enum AsyncTaskStatus<T> {
     /// No task is currently being polled.
     Idle,
diff --git a/src/native/mod.rs b/src/native/mod.rs
index 7c28f3d..a9b2af9 100644
--- a/src/native/mod.rs
+++ b/src/native/mod.rs
@@ -4,14 +4,16 @@ use futures::channel::oneshot;
 use std::{future::Future, pin::Pin};
 
 /// A wrapper type around an async future. The future may be executed
-/// asynchronously by an [`AsyncTaskRunner`] or [`AsyncTaskPool`], or it may be
-/// blocked on the current thread.
+/// asynchronously by an [`AsyncTaskRunner`](crate::AsyncTaskRunner) or
+/// [`AsyncTaskPool`](crate::AsyncTaskPool), or it may be blocked on the current
+/// thread.
 pub struct AsyncTask<T> {
     fut: Pin<Box<dyn Future<Output = ()> + Send + 'static>>,
     receiver: AsyncReceiver<T>,
 }
 
 impl<T> AsyncTask<T> {
+    /// Create an async task from a future.
     pub fn new<F>(fut: F) -> Self
     where
         F: Future<Output = T> + Send + 'static,
@@ -85,7 +87,7 @@ mod test {
 
         match rx.await {
             Ok(v) => assert_eq!(3, v),
-            Err(_) => panic!("the sender dropped"),
+            Err(e) => panic!("the sender dropped ({e})"),
         }
     }
 
diff --git a/src/receiver.rs b/src/receiver.rs
index 9ccbe46..aec0e34 100644
--- a/src/receiver.rs
+++ b/src/receiver.rs
@@ -1,3 +1,4 @@
+/// A channel that catches an [`AsyncTask`](crate::AsyncTask) result.
 pub struct AsyncReceiver<T> {
     pub(crate) received: bool,
     pub(crate) buffer: futures::channel::oneshot::Receiver<T>,
@@ -16,7 +17,7 @@ impl<T> AsyncReceiver<T> {
                 Some(t)
             }
             Ok(None) => None,
-            Err(_) => panic!("the sender was dropped without sending"),
+            Err(e) => panic!("the sender was dropped without sending ({e})"),
         }
     }
 }
diff --git a/src/task_pool.rs b/src/task_pool.rs
index a00e7fd..64f52ab 100644
--- a/src/task_pool.rs
+++ b/src/task_pool.rs
@@ -10,7 +10,8 @@ use bevy::{
     utils::synccell::SyncCell,
 };
 
-/// A task pool which executes [`AsyncTask`]s in the background.
+/// A Bevy [`SystemParam`] to execute many similar [`AsyncTask`]s in the
+/// background simultaneously.
 pub struct AsyncTaskPool<'s, T>(
     pub(crate) &'s mut Vec<Option<AsyncReceiver<T>>>,
 );
@@ -36,16 +37,15 @@ impl<'s, T> AsyncTaskPool<'s, T> {
     pub fn iter_poll(&mut self) -> impl Iterator<Item = AsyncTaskStatus<T>> {
         let mut statuses = vec![];
         self.0.retain_mut(|task| match task {
-            Some(rx) => match rx.try_recv() {
-                Some(v) => {
+            Some(rx) => {
+                if let Some(v) = rx.try_recv() {
                     statuses.push(AsyncTaskStatus::Finished(v));
                     false
-                }
-                None => {
+                } else {
                     statuses.push(AsyncTaskStatus::Pending);
                     true
                 }
-            },
+            }
             None => {
                 statuses.push(AsyncTaskStatus::Idle);
                 true
diff --git a/src/task_runner.rs b/src/task_runner.rs
index bb371de..179caab 100644
--- a/src/task_runner.rs
+++ b/src/task_runner.rs
@@ -10,7 +10,8 @@ use bevy::{
     utils::synccell::SyncCell,
 };
 
-/// A task runner which can execute a single [`AsyncTask`] in the background.
+/// A Bevy [`SystemParam`] to execute [`AsyncTask`]s individually in the
+/// background.
 pub struct AsyncTaskRunner<'s, T>(pub(crate) &'s mut Option<AsyncReceiver<T>>);
 
 impl<'s, T> AsyncTaskRunner<'s, T> {
@@ -49,7 +50,7 @@ impl<'s, T> AsyncTaskRunner<'s, T> {
 
     /// Start an async task in the background. If there is an existing task
     /// pending, it will be dropped and replaced with the given task. If you
-    /// need to run multiple tasks, use the [AsyncTaskPool].
+    /// need to run multiple tasks, use the [`AsyncTaskPool`].
     pub fn start(&mut self, task: impl Into<AsyncTask<T>>) {
         let task = task.into();
         let (fut, rx) = task.into_parts();
diff --git a/src/wasm/mod.rs b/src/wasm/mod.rs
index 557ca41..75c3737 100644
--- a/src/wasm/mod.rs
+++ b/src/wasm/mod.rs
@@ -2,13 +2,17 @@ use crate::AsyncReceiver;
 use futures::channel::oneshot;
 use std::{future::Future, pin::Pin};
 
-/// A task than may be ran by an [`AsyncTaskRunner`], or broken into parts.
+/// A wrapper type around an async future. The future may be executed
+/// asynchronously by an [`AsyncTaskRunner`](crate::AsyncTaskRunner) or
+/// [`AsyncTaskPool`](crate::AsyncTaskPool), or it may be blocked on the current
+/// thread.
 pub struct AsyncTask<T> {
     fut: Pin<Box<dyn Future<Output = ()> + 'static>>,
     receiver: AsyncReceiver<T>,
 }
 
 impl<T> AsyncTask<T> {
+    /// Create an async task from a future.
     pub fn new<F>(fut: F) -> Self
     where
         F: Future<Output = T> + 'static,
@@ -79,7 +83,7 @@ mod test {
 
             match rx.await {
                 Ok(v) => assert_eq!(3, v),
-                Err(_) => panic!("the sender dropped"),
+                Err(e) => panic!("the sender dropped ({e})"),
             }
         });
     }