From 40a18b075dc80048233c54f5cff80658405a9050 Mon Sep 17 00:00:00 2001
From: JuliDi <20155974+JuliDi@users.noreply.github.com>
Date: Sat, 9 Sep 2023 09:50:24 +0200
Subject: [PATCH] improve docstring

---
 embassy-net/src/lib.rs | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/embassy-net/src/lib.rs b/embassy-net/src/lib.rs
index 4922490d..87247c8e 100644
--- a/embassy-net/src/lib.rs
+++ b/embassy-net/src/lib.rs
@@ -367,13 +367,12 @@ impl<D: Driver + 'static> Stack<D> {
     }
 
     /// Wait for the network stack to obtain a valid IP configuration.
-    /// Returns instantly if [`Stack::is_config_up`] returns `true`.
     ///
-    /// ## Watch out:
-    /// The Future is polled only when the [`Stack`] is running,
-    /// e.g. call `spawner.spawn(net_task(stack))`.
+    /// ## Notes:
+    /// - Ensure [`Stack::run`] has been called before using this function.
     ///
-    /// `await`ing before will never yield!
+    /// - This function may never yield (e.g. if no configuration is obtained through DHCP).
+    /// The caller is supposed to handle a timeout for this case.
     ///
     /// ## Example
     /// ```ignore
@@ -385,7 +384,7 @@ impl<D: Driver + 'static> Stack<D> {
     ///    make_static!(embassy_net::StackResources::<2>::new()),
     ///    seed
     /// ));
-    /// // Launch network task
+    /// // Launch network task that runs `stack.run().await`
     /// spawner.spawn(net_task(stack)).unwrap();
     /// // Wait for DHCP config
     /// stack.wait_config_up().await;