From 89b23647f1e510c51d1b6036a8495b4993bafdb3 Mon Sep 17 00:00:00 2001
From: Matthias Seitz <matthias.seitz@outlook.de>
Date: Sun, 5 Mar 2023 21:17:43 +0100
Subject: [PATCH] chore(ws): add some docs and impl debug (#2219)

---
 .../src/rpc/transports/ws/manager.rs          | 23 +++++------
 ethers-providers/src/rpc/transports/ws/mod.rs | 40 +++++++++++++++++--
 2 files changed, 47 insertions(+), 16 deletions(-)

diff --git a/ethers-providers/src/rpc/transports/ws/manager.rs b/ethers-providers/src/rpc/transports/ws/manager.rs
index e8d7af30..d2b57a07 100644
--- a/ethers-providers/src/rpc/transports/ws/manager.rs
+++ b/ethers-providers/src/rpc/transports/ws/manager.rs
@@ -1,3 +1,13 @@
+use super::{
+    backend::{BackendDriver, WsBackend},
+    ActiveSub, ConnectionDetails, InFlight, Instruction, Notification, PubSubItem, Response, SubId,
+    WsClient, WsClientError,
+};
+use crate::JsonRpcError;
+use ethers_core::types::U256;
+use futures_channel::{mpsc, oneshot};
+use futures_util::{select_biased, StreamExt};
+use serde_json::value::RawValue;
 use std::{
     collections::{BTreeMap, HashMap},
     sync::{
@@ -6,19 +16,6 @@ use std::{
     },
 };
 
-use ethers_core::types::U256;
-use futures_channel::{mpsc, oneshot};
-use futures_util::{select_biased, StreamExt};
-use serde_json::value::RawValue;
-
-use crate::JsonRpcError;
-
-use super::{
-    backend::{BackendDriver, WsBackend},
-    ActiveSub, ConnectionDetails, InFlight, Instruction, Notification, PubSubItem, Response, SubId,
-    WsClient, WsClientError,
-};
-
 pub type SharedChannelMap = Arc<Mutex<HashMap<U256, mpsc::UnboundedReceiver<Box<RawValue>>>>>;
 
 pub const DEFAULT_RECONNECTS: usize = 5;
diff --git a/ethers-providers/src/rpc/transports/ws/mod.rs b/ethers-providers/src/rpc/transports/ws/mod.rs
index dc19a245..f694509f 100644
--- a/ethers-providers/src/rpc/transports/ws/mod.rs
+++ b/ethers-providers/src/rpc/transports/ws/mod.rs
@@ -3,7 +3,9 @@
 mod backend;
 
 mod manager;
+
 use manager::{RequestManager, SharedChannelMap};
+use std::fmt;
 
 mod types;
 pub use types::ConnectionDetails;
@@ -12,18 +14,17 @@ pub(self) use types::*;
 mod error;
 pub use error::*;
 
+use crate::{JsonRpcClient, ProviderError, PubsubClient};
 use async_trait::async_trait;
 use ethers_core::types::U256;
 use futures_channel::{mpsc, oneshot};
 use serde::{de::DeserializeOwned, Serialize};
 use serde_json::value::RawValue;
 
-use crate::{JsonRpcClient, ProviderError, PubsubClient};
-
 #[cfg(not(target_arch = "wasm32"))]
 use crate::Authorization;
 
-#[derive(Debug, Clone)]
+#[derive(Clone)]
 pub struct WsClient {
     // Used to send instructions to the `RequestManager`
     instructions: mpsc::UnboundedSender<Instruction>,
@@ -32,12 +33,14 @@ pub struct WsClient {
 }
 
 impl WsClient {
+    /// Establishes a new websocket connection
     pub async fn connect(conn: impl Into<ConnectionDetails>) -> Result<Self, WsClientError> {
         let (man, this) = RequestManager::connect(conn.into()).await?;
         man.spawn();
         Ok(this)
     }
 
+    /// Establishes a new websocket connection with auto-reconnects.
     pub async fn connect_with_reconnects(
         conn: impl Into<ConnectionDetails>,
         reconnects: usize,
@@ -66,6 +69,12 @@ impl WsClient {
     }
 }
 
+impl fmt::Debug for WsClient {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("Ws").finish_non_exhaustive()
+    }
+}
+
 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
 #[cfg_attr(not(target_arch = "wasm32"), async_trait)]
 impl JsonRpcClient for WsClient {
@@ -104,6 +113,31 @@ impl PubsubClient for WsClient {
 
 impl crate::Provider<WsClient> {
     /// Direct connection to a websocket endpoint. Defaults to 5 reconnects.
+    ///
+    /// # Examples
+    ///
+    /// Connect to server via URL
+    ///
+    /// ```
+    /// use ethers_providers::{Ws, Provider};
+    /// use ethers_providers::Middleware;
+    /// # async fn t() {
+    ///     let ws = Provider::<Ws>::connect("ws://localhost:8545").await.unwrap();
+    ///     let _num = ws.get_block_number().await.unwrap();
+    /// # }
+    /// ```
+    ///
+    /// Connect with authentication, see also [Self::connect_with_auth]
+    ///
+    /// ```
+    /// use ethers_providers::{Ws, Provider, Middleware, ConnectionDetails, Authorization };
+    /// # async fn t() {
+    ///     let auth = Authorization::basic("user", "pass");
+    ///     let opts = ConnectionDetails::new("ws://localhost:8545", Some(auth));
+    ///     let ws = Provider::<Ws>::connect(opts).await.unwrap();
+    ///     let _num = ws.get_block_number().await.unwrap();
+    /// # }
+    /// ```
     pub async fn connect(url: impl Into<ConnectionDetails>) -> Result<Self, ProviderError> {
         let ws = crate::Ws::connect(url).await?;
         Ok(Self::new(ws))