From 540cbe45a92fed7bf8649bc7e3fa14513677d860 Mon Sep 17 00:00:00 2001 From: Brendan Blanchard Date: Sat, 3 Aug 2024 14:51:33 -0400 Subject: [PATCH 1/4] Add documentation to `connect_async` --- src/connect.rs | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/src/connect.rs b/src/connect.rs index 5787af15..6ad999a0 100644 --- a/src/connect.rs +++ b/src/connect.rs @@ -10,6 +10,28 @@ use tungstenite::{ use crate::{domain, stream::MaybeTlsStream, Connector, IntoClientRequest, WebSocketStream}; /// Connect to a given URL. +/// +/// Accepts any request that implements [`IntoClientRequest`], which is often just `&str`, but can +/// be a variety of types such as `httparse::Request` or [`tungstenite::http::Request`] for more +/// complex uses. +/// +/// ```no_run +/// use tungstenite::http::{Method, Request}; +/// use tokio_tungstenite::connect_async; +/// +/// let request = Request::builder() +/// .uri("wss://api.example.com") +/// .method(Method::GET) +/// .header("Sec-WebSocket-Key", "someUniqueValue") +/// .header("Sec-WebSocket-Version", "13") +/// .header("host", "api.example.com") +/// .header("Connection", "Upgrade") +/// .header("Upgrade", "websocket") +/// .body(()) +/// .unwrap(); +/// +/// let (stream, response) = connect_async(request).await.unwrap(); +/// ``` pub async fn connect_async( request: R, ) -> Result<(WebSocketStream>, Response), Error> From 1798186a10c78f1c86ac9f49c62feae259461c9d Mon Sep 17 00:00:00 2001 From: Brendan Blanchard Date: Sat, 3 Aug 2024 14:53:22 -0400 Subject: [PATCH 2/4] Add hidden async wrapper function --- src/connect.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/connect.rs b/src/connect.rs index 6ad999a0..7839c290 100644 --- a/src/connect.rs +++ b/src/connect.rs @@ -16,6 +16,7 @@ use crate::{domain, stream::MaybeTlsStream, Connector, IntoClientRequest, WebSoc /// complex uses. /// /// ```no_run +/// # async fn example() { /// use tungstenite::http::{Method, Request}; /// use tokio_tungstenite::connect_async; /// @@ -31,6 +32,7 @@ use crate::{domain, stream::MaybeTlsStream, Connector, IntoClientRequest, WebSoc /// .unwrap(); /// /// let (stream, response) = connect_async(request).await.unwrap(); +/// #} /// ``` pub async fn connect_async( request: R, From 19cd2c04880acb6679a7b35865af1cb3d0a9a839 Mon Sep 17 00:00:00 2001 From: Brendan Blanchard Date: Tue, 6 Aug 2024 06:50:03 -0400 Subject: [PATCH 3/4] Reduce example, fix doc format --- src/connect.rs | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/src/connect.rs b/src/connect.rs index 7839c290..f8797d99 100644 --- a/src/connect.rs +++ b/src/connect.rs @@ -16,23 +16,17 @@ use crate::{domain, stream::MaybeTlsStream, Connector, IntoClientRequest, WebSoc /// complex uses. /// /// ```no_run -/// # async fn example() { +/// # use tungstenite::client::IntoClientRequest; +/// +/// # async fn main() { /// use tungstenite::http::{Method, Request}; /// use tokio_tungstenite::connect_async; /// -/// let request = Request::builder() -/// .uri("wss://api.example.com") -/// .method(Method::GET) -/// .header("Sec-WebSocket-Key", "someUniqueValue") -/// .header("Sec-WebSocket-Version", "13") -/// .header("host", "api.example.com") -/// .header("Connection", "Upgrade") -/// .header("Upgrade", "websocket") -/// .body(()) -/// .unwrap(); +/// let mut request = "wss://api.example.com".into_client_request().unwrap(); +/// request.headers_mut().insert("api-key", "42".parse().unwrap()); /// /// let (stream, response) = connect_async(request).await.unwrap(); -/// #} +/// # } /// ``` pub async fn connect_async( request: R, From eb21d7438fad4069bf97397b3649d249ef4fa170 Mon Sep 17 00:00:00 2001 From: Brendan Blanchard Date: Thu, 8 Aug 2024 06:46:55 -0400 Subject: [PATCH 4/4] Avoid `main` as the test function name --- src/connect.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connect.rs b/src/connect.rs index f8797d99..989349a9 100644 --- a/src/connect.rs +++ b/src/connect.rs @@ -18,7 +18,7 @@ use crate::{domain, stream::MaybeTlsStream, Connector, IntoClientRequest, WebSoc /// ```no_run /// # use tungstenite::client::IntoClientRequest; /// -/// # async fn main() { +/// # async fn test() { /// use tungstenite::http::{Method, Request}; /// use tokio_tungstenite::connect_async; ///