From daca80328064d3ac42511fbcacc43db5801f4224 Mon Sep 17 00:00:00 2001
From: x <x@x>
Date: Thu, 31 Aug 2023 13:14:49 +0200
Subject: [PATCH] sys: improve docstring for CondVar

---
 src/system/condvar.rs | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/src/system/condvar.rs b/src/system/condvar.rs
index d258c686e..e41136cb4 100644
--- a/src/system/condvar.rs
+++ b/src/system/condvar.rs
@@ -23,7 +23,25 @@ use std::{
     task::{Context, Poll, Waker},
 };
 
-/// Condition variable which allows a task to block until woken up
+/// Condition variables allow you to block a task while waiting for an event to occur.
+/// Condition variables are typically associated with a boolean predicate (a condition).
+/// ```rust
+///    let cv = Arc::new(CondVar::new());
+///
+///    let cv_ = cv.clone();
+///    executor_
+///        .spawn(async move {
+///            // Waits here until notify() is called
+///            cv_.wait().await;
+///            // Check for some condition...
+///        })
+///        .detach();
+///
+///    // Allow above code to continue
+///    cv.notify();
+/// ```
+/// After the condition variable is woken up, the user may `wait` again for another `notify`
+/// signal by first calling `cv_.reset()`.
 pub struct CondVar {
     state: Mutex<CondVarState>,
 }