Merge pull request #361 from alexheretic/docs++

Clarify `WebSocketConfig` docs

Author: daniel-abramov

src/protocol/mod.rs

@@ -42,13 +42,21 @@ pub struct WebSocketConfig {
     /// to the underlying stream.
     /// The default value is 128 KiB.
     ///
+    /// If set to `0` each message will be eagerly written to the underlying stream.
+    /// It is often more optimal to allow them to buffer a little, hence the default value.
+    ///
     /// Note: [`flush`](WebSocket::flush) will always fully write the buffer regardless.
     pub write_buffer_size: usize,
     /// The max size of the write buffer in bytes. Setting this can provide backpressure
     /// in the case the write buffer is filling up due to write errors.
     /// The default value is unlimited.
     ///
-    /// Note: Should always be set higher than [`write_buffer_size`](Self::write_buffer_size).
+    /// Note: The write buffer only builds up past [`write_buffer_size`](Self::write_buffer_size)
+    /// when writes to the underlying stream are failing. So the **write buffer can not
+    /// fill up if you are not observing write errors even if not flushing**.
+    ///
+    /// Note: Should always be at least [`write_buffer_size + 1 message`](Self::write_buffer_size)
+    /// and probably a little more depending on error handling strategy.
     pub max_write_buffer_size: usize,
     /// The maximum size of a message. `None` means no size limit. The default value is 64 MiB
     /// which should be reasonably big for all normal use-cases but small enough to prevent