From 496ad4ed43ab3b0948553d371709771c010de565 Mon Sep 17 00:00:00 2001
From: huntc <huntchr@gmail.com>
Date: Wed, 1 Dec 2021 09:29:45 +1100
Subject: [PATCH] Rationale for uarte usage

---
 embassy-nrf/src/buffered_uarte.rs |  4 ++++
 embassy-nrf/src/uarte.rs          | 11 +++++++++++
 2 files changed, 15 insertions(+)

diff --git a/embassy-nrf/src/buffered_uarte.rs b/embassy-nrf/src/buffered_uarte.rs
index 9763774d..5468f6c0 100644
--- a/embassy-nrf/src/buffered_uarte.rs
+++ b/embassy-nrf/src/buffered_uarte.rs
@@ -1,3 +1,7 @@
+//! Async buffered UART
+//!
+//! Please ee [uarte] to understand when [BufferedUarte] should be used.
+
 use core::cmp::min;
 use core::marker::PhantomData;
 use core::mem;
diff --git a/embassy-nrf/src/uarte.rs b/embassy-nrf/src/uarte.rs
index 543f7fb7..60e69e03 100644
--- a/embassy-nrf/src/uarte.rs
+++ b/embassy-nrf/src/uarte.rs
@@ -1,6 +1,17 @@
 #![macro_use]
 
 //! Async UART
+//!
+//! Async UART is provided in two flavors - this one and also [buffered_uarte::BufferedUarte].
+//! The [Uarte] here is useful for those use-cases where reading the UARTE peripheral is
+//! exclusively awaited on. If the [Uarte] is required to be awaited on with some other future,
+//! for example when using `futures_util::future::select`, then you should consider
+//! [buffered_uarte::BufferedUarte] so that reads may continue while processing these
+//! other futures. If you do not then you may lose data between reads.
+//!
+//! An advantage of the [Uarte] has over [buffered_uarte::BufferedUarte] is that less
+//! memory may be used given that buffers are passed in directly to its read and write
+//! methods.
 
 use core::future::Future;
 use core::marker::PhantomData;