docs(endpoint): add detail & example to online method

iroh/src/endpoint.rs

@@ -899,6 +899,30 @@ impl Endpoint {
     /// To understand if the endpoint has gone back "offline",
     /// you must use the [`Endpoint::watch_addr`] method, to
     /// get information on the current relay and direct address information.
+    ///
+    /// Keep in mind that in the common case where the endpoint's configured relay
+    /// servers are only accessible via a wide are connection, this method will
+    /// await indefinitely when the endpoint has no WAN connection. If you're writing
+    /// an app that's designed to work without a WAN connection, defer any calls to
+    /// `online` as long as possible, or avoid calling `online` entirely.
+    ///
+    /// # Examples
+    ///
+    /// ```no run
+    /// use iroh::Endpoint;
+    ///
+    /// #[tokio::main]
+    /// async fn main() {
+    /// // after this await returns, the endpoint is bound to a local socket
+    /// // and can be dialed, but almost certainly hasn't finished picking a
+    /// // relay
+    /// let endpoint = Endpoint::bind().await;
+    ///
+    /// // after this await returns we have a connection to at least one relay
+    /// // and holepunching should work as expected.
+    /// endpoint.online().await;
+    /// }
+    /// ```
     pub async fn online(&self) {
         self.msock.home_relay().initialized().await;
     }