Improve awc websocket docs (#1654)

Co-authored-by: Rob Ede <robjtede@icloud.com>

awc/src/lib.rs

@@ -193,7 +193,8 @@ impl Client {
         self.request(Method::OPTIONS, url)
     }
 
-    /// Construct WebSockets request.
+    /// Initialize a WebSocket connection.
+    /// Returns a WebSocket connection builder.
     pub fn ws<U>(&self, url: U) -> ws::WebsocketsRequest
     where
         Uri: TryFrom<U>,

awc/src/ws.rs

@@ -1,4 +1,31 @@
 //! Websockets client
+//!
+//! Type definitions required to use [`awc::Client`](../struct.Client.html) as a WebSocket client.
+//!
+//! # Example
+//!
+//! ```
+//! use awc::{Client, ws};
+//! use futures_util::{sink::SinkExt, stream::StreamExt};
+//!
+//! #[actix_rt::main]
+//! async fn main() {
+//!     let (_resp, mut connection) = Client::new()
+//!         .ws("ws://echo.websocket.org")
+//!         .connect()
+//!         .await
+//!         .unwrap();
+//!
+//!     connection
+//!         .send(ws::Message::Text("Echo".to_string()))
+//!         .await
+//!         .unwrap();
+//!     let response = connection.next().await.unwrap().unwrap();
+//!
+//!     assert_eq!(response, ws::Frame::Text("Echo".as_bytes().into()));
+//! }
+//! ```
+
 use std::convert::TryFrom;
 use std::net::SocketAddr;
 use std::rc::Rc;