Merge #741

741: Docs 2 r=korken89 a=datdenkikniet

Working on the migration guide and other docs

TODO:
- [x] Migration guide
- [x] Hardcoded examples should link to example code that is tested (this was already done, AFAICT)
- [x] Address #699 
- [x] Discuss: should we remove references to non-v2, apart from the migration guide and link to the book for v1? (Off-github conclusion: yes)
- [x] RTIC {vs,and} Embassy (important: distinction between embassy runtime & HALs)
- [x] More descriptive docs on how to implement & PR implementations of `Monotonic` to `rtic-monotonics` 


Co-authored-by: datdenkikniet <jcdra1@gmail.com>

1 files changed, 14 insertions, 12 deletions

diff --git a/book/en/src/by-example/channel.md b/book/en/src/by-example/channel.md
index c020870..75ecbfd 100644
--- a/book/en/src/by-example/channel.md
+++ b/book/en/src/by-example/channel.md
@@ -1,8 +1,8 @@
 # Communication over channels.
 
-Channels can be used to communicate data between running *software* tasks. The channel is essentially a wait queue, allowing tasks with multiple producers and a single receiver. A channel is constructed in the `init` task and backed by statically allocated memory. Send and receive endpoints are distributed to *software* tasks:
+Channels can be used to communicate data between running tasks. The channel is essentially a wait queue, allowing tasks with multiple producers and a single receiver. A channel is constructed in the `init` task and backed by statically allocated memory. Send and receive endpoints are distributed to *software* tasks:
 
-``` rust
+``` rust,noplayground
 ...
 const CAPACITY: usize = 5;
 #[init]
@@ -16,11 +16,13 @@ const CAPACITY: usize = 5;
 
 In this case the channel holds data of `u32` type with a capacity of 5  elements. 
 
+Channels can also be used from *hardware* tasks, but only in a non-`async` manner using the [Try API](#try-api).
+
 ## Sending data
 
 The `send` method post a message on the channel as shown below:
 
-``` rust
+``` rust,noplayground
 #[task]
 async fn sender1(_c: sender1::Context, mut sender: Sender<'static, u32, CAPACITY>) {
     hprintln!("Sender 1 sending: 1");
@@ -32,7 +34,7 @@ async fn sender1(_c: sender1::Context, mut sender: Sender<'static, u32, CAPACITY
 
 The receiver can `await` incoming messages:
 
-``` rust
+``` rust,noplayground
 #[task]
 async fn receiver(_c: receiver::Context, mut receiver: Receiver<'static, u32, CAPACITY>) {
     while let Ok(val) = receiver.recv().await {
@@ -46,7 +48,7 @@ Channels are implemented using a small (global) *Critical Section* (CS) for prot
 
 For a complete example:
 
-``` rust
+``` rust,noplayground
 {{#include ../../../../rtic/examples/async-channel.rs}}
 ```
 
@@ -62,7 +64,7 @@ Also sender endpoint can be awaited. In case the channel capacity has not yet be
 
 In the following example the `CAPACITY` has been reduced to 1, forcing sender tasks to wait until the data in the channel has been received.
 
-``` rust
+``` rust,noplayground
 {{#include ../../../../rtic/examples/async-channel-done.rs}}
 ```
 
@@ -79,7 +81,7 @@ $ cargo run --target thumbv7m-none-eabi --example async-channel-done --features
 
 In case all senders have been dropped `await`-ing on an empty receiver channel results in an error. This allows to gracefully implement different types of shutdown operations.
 
-``` rust
+``` rust,noplayground
 {{#include ../../../../rtic/examples/async-channel-no-sender.rs}}
 ```
 
@@ -95,7 +97,7 @@ Similarly, `await`-ing on a send channel results in an error in case the receive
 
 The resulting error returns the data back to the sender, allowing the sender to take appropriate action (e.g., storing the data to later retry sending it).
 
-``` rust
+``` rust,noplayground
 {{#include ../../../../rtic/examples/async-channel-no-receiver.rs}}
 ```
 
@@ -107,13 +109,13 @@ $ cargo run --target thumbv7m-none-eabi --example async-channel-no-receiver --fe
 {{#include ../../../../rtic/ci/expected/async-channel-no-receiver.run}}
 ```
 
-
-
 ## Try API
 
-In cases you wish the sender to proceed even in case the channel is full. To that end, a `try_send` API is provided.
+Using the Try API, you can send or receive data from or to a channel without requiring that the operation succeeds, and in non-`async` contexts.
+
+This API is exposed through `Receiver::try_recv` and `Sender::try_send`.
 
-``` rust
+``` rust,noplayground
 {{#include ../../../../rtic/examples/async-channel-try.rs}}
 ```