docs

2 files changed, 6 insertions, 1 deletions

diff --git a/embassy-sync/README.md b/embassy-sync/README.md
index cc65cf6ef..55618f72d 100644
--- a/embassy-sync/README.md
+++ b/embassy-sync/README.md
@@ -5,6 +5,7 @@ An [Embassy](https://embassy.dev) project.
 Synchronization primitives and data structures with async support:
 
 - [`Channel`](channel::Channel) - A Multiple Producer Multiple Consumer (MPMC) channel. Each message is only received by a single consumer.
+- [`PriorityChannel`](channel::priority::PriorityChannel) - A Multiple Producer Multiple Consumer (MPMC) channel. Each message is only received by a single consumer. Higher priority items are sifted to the front of the channel.
 - [`PubSubChannel`](pubsub::PubSubChannel) - A broadcast channel (publish-subscribe) channel. Each message is received by all consumers.
 - [`Signal`](signal::Signal) - Signalling latest value to a single consumer.
 - [`Mutex`](mutex::Mutex) - Mutex for synchronizing state between asynchronous tasks.
diff --git a/embassy-sync/src/channel/priority.rs b/embassy-sync/src/channel/priority.rs
index 1fd137db5..61dc7be68 100644
--- a/embassy-sync/src/channel/priority.rs
+++ b/embassy-sync/src/channel/priority.rs
@@ -323,7 +323,9 @@ where
 /// buffer is full, attempts to `send` new messages will wait until a message is
 /// received from the channel.
 ///
-/// All data sent will become available in the same order as it was sent.
+/// Sent data may be reordered based on their priorty within the channel.
+/// For example, in a [`Max`](heapless::binary_heap::Max) [`PriorityChannel`]
+/// containing `u32`'s, data sent in the following order `[1, 2, 3]` will be recieved as `[3, 2, 1]`.
 pub struct PriorityChannel<M, T, K, const N: usize>
 where
     T: Ord,
@@ -509,8 +511,10 @@ mod tests {
         // Prio channel with kind `Max` sifts larger numbers to the front of the queue
         let mut c = ChannelState::<u32, Max, 3>::new();
         assert!(c.try_send(1).is_ok());
+        assert!(c.try_send(2).is_ok());
         assert!(c.try_send(3).is_ok());
         assert_eq!(c.try_receive().unwrap(), 3);
+        assert_eq!(c.try_receive().unwrap(), 2);
         assert_eq!(c.try_receive().unwrap(), 1);
     }