Rationale for uarte usage

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;

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;