Add more docs and cross-links

3 files changed, 20 insertions, 7 deletions

diff --git a/docs/pages/faq.adoc b/docs/pages/faq.adoc
index a2f56a539..fc1316062 100644
--- a/docs/pages/faq.adoc
+++ b/docs/pages/faq.adoc
@@ -352,7 +352,8 @@ There are two main ways to handle concurrency in Embassy:
 
 In general, either of these approaches will work. The main differences of these approaches are:
 
-When using **separate tasks**, each task needs its own RAM allocation, so there's a little overhead for each task, so one task that does three things will likely be a little bit smaller than three tasks that do one thing (not a lot, probably a couple dozen bytes). In contrast, with **multiple futures in one task**, you don't need multiple task allocations, and it will generally be easier to share data, or use borrowed resources, inside of a single task.
+When using **separate tasks**, each task needs its own RAM allocation, so there's a little overhead for each task, so one task that does three things will likely be a little bit smaller than three tasks that do one thing (not a lot, probably a couple dozen bytes). In contrast, with **multiple futures in one task**, you don't need multiple task allocations, and it will generally be easier to share data, or use borrowed resources, inside of a single task. 
+An example showcasing some methods for sharing things between tasks link:https://github.com/embassy-rs/embassy/blob/main/examples/rp/src/bin/sharing.rs[can be found here].
 
 But when it comes to "waking" tasks, for example when a data transfer is complete or a button is pressed, it's faster to wake a dedicated task, because that task does not need to check which future is actually ready. `join` and `select` must check ALL of the futures they are managing to see which one (or which ones) are ready to do more work. This is because all Rust executors (like Embassy or Tokio) only have the ability to wake tasks, not specific futures. This means you will use slightly less CPU time juggling futures when using dedicated tasks.
 
diff --git a/docs/pages/sharing_peripherals.adoc b/docs/pages/sharing_peripherals.adoc
index 6bcd56b01..ebd899c4e 100644
--- a/docs/pages/sharing_peripherals.adoc
+++ b/docs/pages/sharing_peripherals.adoc
@@ -126,3 +126,5 @@ async fn toggle_led(control: Sender<'static, ThreadModeRawMutex, LedState, 64>,
 
 This example replaces the Mutex with a Channel, and uses another task (the main loop) to drive the LED. The advantage of this approach is that only a single task references the peripheral, separating concerns. However, using a Mutex has a lower overhead and might be necessary if you need to ensure
 that the operation is completed before continuing to do other work in your task.
+
+An example showcasing more methods for sharing link:https://github.com/embassy-rs/embassy/blob/main/examples/rp/src/bin/sharing.rs[can be found here].
\ No newline at end of file
diff --git a/examples/rp/src/bin/sharing.rs b/examples/rp/src/bin/sharing.rs
index 0761500ef..5416e20ce 100644
--- a/examples/rp/src/bin/sharing.rs
+++ b/examples/rp/src/bin/sharing.rs
@@ -1,4 +1,14 @@
 //! This example shows some common strategies for sharing resources between tasks.
+//!
+//! We demonstrate five different ways of sharing, covering different use cases:
+//! - Atomics: This method is used for simple values, such as bool and u8..u32
+//! - Blocking Mutex: This is used for sharing non-async things, using Cell/RefCell for interior mutability.
+//! - Async Mutex: This is used for sharing async resources, where you need to hold the lock across await points.
+//!   The async Mutex has interior mutability built-in, so no RefCell is needed.
+//! - Cell: For sharing Copy types between tasks running on the same executor.
+//! - RefCell: When you want &mut access to a value shared between tasks running on the same executor.
+//!
+//! More information: https://embassy.dev/book/#_sharing_peripherals_between_tasks
 
 #![no_std]
 #![no_main]
@@ -21,7 +31,7 @@ use rand::RngCore;
 use static_cell::{ConstStaticCell, StaticCell};
 use {defmt_rtt as _, panic_probe as _};
 
-type UartMutex = mutex::Mutex<CriticalSectionRawMutex, UartTx<'static, UART0, uart::Async>>;
+type UartAsyncMutex = mutex::Mutex<CriticalSectionRawMutex, UartTx<'static, UART0, uart::Async>>;
 
 struct MyType {
     inner: u32,
@@ -53,7 +63,7 @@ fn main() -> ! {
 
     let uart = UartTx::new(p.UART0, p.PIN_0, p.DMA_CH0, uart::Config::default());
     // Use the async Mutex for sharing async things (built-in interior mutability)
-    static UART: StaticCell<UartMutex> = StaticCell::new();
+    static UART: StaticCell<UartAsyncMutex> = StaticCell::new();
     let uart = UART.init(mutex::Mutex::new(uart));
 
     // High-priority executor: runs in interrupt mode
@@ -80,7 +90,7 @@ fn main() -> ! {
 }
 
 #[embassy_executor::task]
-async fn task_a(uart: &'static UartMutex) {
+async fn task_a(uart: &'static UartAsyncMutex) {
     let mut ticker = Ticker::every(Duration::from_secs(1));
     loop {
         let random = RoscRng.next_u32();
@@ -100,7 +110,7 @@ async fn task_a(uart: &'static UartMutex) {
 }
 
 #[embassy_executor::task]
-async fn task_b(uart: &'static UartMutex, cell: &'static Cell<[u8; 4]>, ref_cell: &'static RefCell<MyType>) {
+async fn task_b(uart: &'static UartAsyncMutex, cell: &'static Cell<[u8; 4]>, ref_cell: &'static RefCell<MyType>) {
     let mut ticker = Ticker::every(Duration::from_secs(1));
     loop {
         let random = RoscRng.next_u32();
@@ -121,8 +131,8 @@ async fn task_c(cell: &'static Cell<[u8; 4]>, ref_cell: &'static RefCell<MyType>
     loop {
         info!("=======================");
 
-        let atomic = ATOMIC.load(Ordering::Relaxed);
-        info!("atomic: {}", atomic);
+        let atomic_val = ATOMIC.load(Ordering::Relaxed);
+        info!("atomic: {}", atomic_val);
 
         MUTEX_BLOCKING.lock(|x| {
             let val = x.borrow().inner;