From d21958f5d2c610097113313283c6ccd983bfb4c0 Mon Sep 17 00:00:00 2001
From: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
Date: Tue, 28 Feb 2023 19:18:54 +0100
Subject: [PATCH 1/2] Improve the docs of `connect` and `serve`

---
 clippy.toml                               |  1 +
 crates/re_sdk/src/session.rs              | 25 +++++++++++++++++++----
 crates/re_viewer/src/remote_viewer_app.rs |  2 +-
 rerun_py/rerun_sdk/rerun/__init__.py      |  8 +++++++-
 4 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/clippy.toml b/clippy.toml
index cbeea80f79e8..282db13f3d53 100644
--- a/clippy.toml
+++ b/clippy.toml
@@ -53,4 +53,5 @@ doc-valid-idents = [
   "sRGB",
   "sRGBA",
   "WebGL",
+  "WebSockets",
 ]
diff --git a/crates/re_sdk/src/session.rs b/crates/re_sdk/src/session.rs
index 0820f99b1da8..b01240b62f0a 100644
--- a/crates/re_sdk/src/session.rs
+++ b/crates/re_sdk/src/session.rs
@@ -174,12 +174,23 @@ impl Session {
         self.recording_source = recording_source;
     }
 
-    /// Send log data to a remote server.
+    /// Send log data to a remote viewer/server.
+    ///
+    /// Usually this is done by running the `rerun` binary (`cargo install rerun`) without arguments,
+    /// and then connecting to it.
     ///
     /// Send all currently buffered messages.
     /// If we are already connected, we will re-connect to this new address.
     ///
+    /// This function returns immediately.
     /// Disconnect with [`Self::disconnect`].
+    ///
+    /// ## Example:
+    ///
+    /// ``` no_run
+    /// # let mut session = todo!();
+    /// session.connect(rerun::default_server_addr());
+    /// ```
     pub fn connect(&mut self, addr: SocketAddr) {
         if !self.enabled {
             re_log::debug!("Rerun disabled - call to connect() ignored");
@@ -209,10 +220,16 @@ impl Session {
         }
     }
 
-    /// Serve a Rerun web viewer and stream the log messages to it.
+    /// Serve log-data over WebSockets and serve a Rerun web viewer over HTTP.
+    ///
+    /// If the `open_browser` argument is `true`, your default browser
+    /// will be opened with a connected web-viewer.
+    ///
+    /// If not, you can connect to this server using the `rerun` binary (`cargo install rerun`).
+    ///
+    /// NOTE: you can not connect one `Session` to another.
     ///
-    /// If the `open_browser` argument is set, your default browser
-    /// will be opened to show the viewer.
+    /// This function returns immediately.
     #[cfg(feature = "web_viewer")]
     pub fn serve(&mut self, open_browser: bool) {
         if !self.enabled {
diff --git a/crates/re_viewer/src/remote_viewer_app.rs b/crates/re_viewer/src/remote_viewer_app.rs
index 043fdf00ef8b..240ea2a6af87 100644
--- a/crates/re_viewer/src/remote_viewer_app.rs
+++ b/crates/re_viewer/src/remote_viewer_app.rs
@@ -1,6 +1,6 @@
 use crate::App;
 
-/// Connects to a server over `WebSockets`.
+/// Connects to a server over WebSockets.
 pub struct RemoteViewerApp {
     build_info: re_build_info::BuildInfo,
     app_env: crate::AppEnvironment,
diff --git a/rerun_py/rerun_sdk/rerun/__init__.py b/rerun_py/rerun_sdk/rerun/__init__.py
index e76af6231598..42109f26c54c 100644
--- a/rerun_py/rerun_sdk/rerun/__init__.py
+++ b/rerun_py/rerun_sdk/rerun/__init__.py
@@ -222,6 +222,8 @@ def connect(addr: Optional[str] = None) -> None:
 
     Requires that you first start a Rerun Viewer, e.g. with 'python -m rerun'
 
+    This function returns immediately.
+
     Parameters
     ----------
     addr
@@ -287,10 +289,14 @@ def spawn(port: int = 9876, connect: bool = True) -> None:
 
 def serve(open_browser: bool = True) -> None:
     """
-    Serve a Rerun Web Viewer.
+    Serve log-data over WebSockets and serve a Rerun web viewer over HTTP.
+
+    You can connect to this server using `python -m rerun`.
 
     WARNING: This is an experimental feature.
 
+    This function returns immediately.
+
     Parameters
     ----------
     open_browser

From 38190475a7658d340fc1630f46075356bcc27c01 Mon Sep 17 00:00:00 2001
From: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
Date: Tue, 28 Feb 2023 19:34:11 +0100
Subject: [PATCH 2/2] Fix doctest

---
 crates/re_sdk/src/session.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/crates/re_sdk/src/session.rs b/crates/re_sdk/src/session.rs
index b01240b62f0a..eca0ab9cb8b7 100644
--- a/crates/re_sdk/src/session.rs
+++ b/crates/re_sdk/src/session.rs
@@ -188,8 +188,8 @@ impl Session {
     /// ## Example:
     ///
     /// ``` no_run
-    /// # let mut session = todo!();
-    /// session.connect(rerun::default_server_addr());
+    /// # let mut session = re_sdk::Session::new();
+    /// session.connect(re_sdk::default_server_addr());
     /// ```
     pub fn connect(&mut self, addr: SocketAddr) {
         if !self.enabled {