Add poll_write docs (hyperium#73)

tokio-rustls/src/lib.rs

@@ -1,4 +1,40 @@
 //! Asynchronous TLS/SSL streams for Tokio using [Rustls](https://github.com/ctz/rustls).
+//!
+//! # Why do I need to call `poll_flush`?
+//!
+//! Most TLS implementations will have an internal buffer to improve throughput,
+//! and rustls is no exception.
+//!
+//! When we write data to `TlsStream`, we always write rustls buffer first,
+//! then take out rustls encrypted data packet, and write it to data channel (like TcpStream).
+//! When data channel is pending, some data may remain in rustls buffer.
+//!
+//! `tokio-rustls` To keep it simple and correct, [TlsStream] will behave like `BufWriter`.
+//! For `TlsStream<TcpStream>`, this means that data written by `poll_write` is not guaranteed to be written to `TcpStream`.
+//! You must call `poll_flush` to ensure that it is written to `TcpStream`.
+//!
+//! You should call `poll_flush` at the appropriate time,
+//! such as when a period of `poll_write` write is complete and there is no more data to write.
+//!
+//! ## Why don't we write during `poll_read`?
+//!
+//! We did this in the early days of `tokio-rustls`, but it caused some bugs.
+//! We can solve these bugs through some solutions, but this will cause performance degradation (reverse false wakeup).
+//!
+//! And reverse write will also prevent us implement full duplex in the future.
+//!
+//! see <https://github.com/tokio-rs/tls/issues/40>
+//!
+//! ## Why can't we handle it like `native-tls`?
+//!
+//! When data channel returns to pending, `native-tls` will falsely report the number of bytes it consumes.
+//! This means that if data written by `poll_write` is not actually written to data channel, it will not return `Ready`.
+//! Thus avoiding the call of `poll_flush`.
+//!
+//! but which does not conform to convention of `AsyncWrite` trait.
+//! This means that if you give inconsistent data in two `poll_write`, it may cause unexpected behavior.
+//!
+//! see <https://github.com/tokio-rs/tls/issues/41>
 
 macro_rules! ready {
     ( $e:expr ) => {