Fix and write Documentation

Author: skade

src/acceptor.rs

@@ -12,31 +12,35 @@ use std::io;
 /// The TLS accepting part. The acceptor drives
 /// the server side of the TLS handshake process. It works
 /// on any asynchronous stream.
-/// 
+///
 /// It provides a simple interface (`accept`), returning a future
 /// that will resolve when the handshake process completed. On
 /// success, it will hand you an async `TLSStream`.
-/// 
+///
 /// ## Example
-/// 
-/// ```rust
-/// let mut stream = acceptor.accept(stream).await?;
-/// ```
+///
+/// See /examples/server for an example.
 #[derive(Clone)]
 pub struct TlsAcceptor {
     inner: Arc<ServerConfig>,
 }
 
 impl TlsAcceptor {
+    /// Accept a client connections. `stream` can be any type implementing `AsyncRead` and `AsyncWrite`,
+    /// such as TcpStreams or Unix domain sockets.
+    ///
+    /// Otherwise, it will return a `Accept` Future, representing the Acceptance part of a
+    /// Tls handshake. It will resolve when the handshake is over.
+    #[inline]
     pub fn accept<IO>(&self, stream: IO) -> Accept<IO>
     where
         IO: AsyncRead + AsyncWrite + Unpin,
     {
         self.accept_with(stream, |_| ())
     }
 
-    #[inline]
-    pub fn accept_with<IO, F>(&self, stream: IO, f: F) -> Accept<IO>
+    // Currently private, as exposing ServerSessions exposes rusttls
+    fn accept_with<IO, F>(&self, stream: IO, f: F) -> Accept<IO>
     where
         IO: AsyncRead + AsyncWrite + Unpin,
         F: FnOnce(&mut ServerSession),

src/client.rs

@@ -9,8 +9,8 @@ use std::{io, mem};
 
 use rustls::Session;
 
-/// A wrapper around an underlying raw stream which implements the TLS or SSL
-/// protocol.
+/// The client end of a TLS connection. Can be used like any other bidirectional IO stream.
+/// Wraps the underlying TCP stream.
 #[derive(Debug)]
 pub struct TlsStream<IO> {
     pub(crate) io: IO,
@@ -28,6 +28,8 @@ pub(crate) enum MidHandshake<IO> {
     End,
 }
 
+// TODO unexpose, maybe without Client?
+
 impl<IO> TlsStream<IO> {
     #[inline]
     pub fn get_ref(&self) -> (&IO, &ClientSession) {

src/connector.rs

@@ -17,12 +17,26 @@ use webpki::DNSNameRef;
 /// 
 /// It provides a simple interface (`connect`), returning a future
 /// that will resolve when the handshake process completed. On
-/// success, it will hand you an async `TLSStream`.
+/// success, it will hand you an async `TlsStream`.
 /// 
+/// To create a `TlsConnector` with a non-default configuation, create
+/// a `rusttls::ClientConfig` and call `.into()` on it.
+///
 /// ## Example
 /// 
 /// ```rust
-/// let mut stream = acceptor.accept(stream).await?;
+/// #![feature(async_await)]
+///
+/// use async_tls::TlsConnector;
+///
+/// async_std::task::block_on(async {
+///     let connector = TlsConnector::default();
+///     let tcp_stream = async_std::net::TcpStream::connect("example.com").await?;
+///     let handshake = connector.connect("example.com", tcp_stream)?;
+///     let encrypted_stream = handshake.await?;
+///
+///     Ok(()) as async_std::io::Result<()>
+/// });
 /// ```
 #[derive(Clone)]
 pub struct TlsConnector {
@@ -52,29 +66,39 @@ impl Default for TlsConnector {
 }
 
 impl TlsConnector {
+    /// Create a new TlsConnector with default configuration.
+    /// 
+    /// This is the same as calling `TlsConnector::default()`.
     pub fn new() -> Self {
         Default::default()
     }
 
     /// Enable 0-RTT.
     ///
-    /// Note that you want to use 0-RTT.
-    /// You must set `enable_early_data` to `true` in `ClientConfig`.
+    /// You must also set `enable_early_data` to `true` in `ClientConfig`.
     #[cfg(feature = "early-data")]
     pub fn early_data(mut self, flag: bool) -> TlsConnector {
         self.early_data = flag;
         self
     }
 
+    /// Connect to a server. `stream` can be any type implementing `AsyncRead` and `AsyncWrite`,
+    /// such as TcpStreams or Unix domain sockets.
+    ///
+    /// The function will return an error if the domain is not of valid format.
+    /// Otherwise, it will return a `Connect` Future, representing the connecting part of a
+    /// Tls handshake. It will resolve when the handshake is over.
+    #[inline]
     pub fn connect<'a, IO>(&self, domain: impl AsRef<str>, stream: IO) -> io::Result<Connect<IO>>
     where
         IO: AsyncRead + AsyncWrite + Unpin,
     {
         self.connect_with(domain, stream, |_| ())
     }
 
-    #[inline]
-    pub fn connect_with<'a, IO, F>(
+    // NOTE: Currently private, exposing ClientSession exposes rusttls
+    // Early data should be exposed differently
+    fn connect_with<'a, IO, F>(
         &self,
         domain: impl AsRef<str>,
         stream: IO,

src/server.rs

@@ -10,8 +10,8 @@ use std::{io, mem};
 
 use rustls::Session;
 
-/// A wrapper around an underlying raw stream which implements the TLS or SSL
-/// protocol.
+/// The server end of a TLS connection. Can be used like any other bidirectional IO stream.
+/// Wraps the underlying TCP stream.
 #[derive(Debug)]
 pub struct TlsStream<IO> {
     pub(crate) io: IO,
@@ -24,6 +24,7 @@ pub(crate) enum MidHandshake<IO> {
     End,
 }
 
+// TODO unexpose, maybe without ServerSession?
 impl<IO> TlsStream<IO> {
     #[inline]
     pub fn get_ref(&self) -> (&IO, &ServerSession) {
@@ -53,7 +54,7 @@ where
 
         if let MidHandshake::Handshaking(stream) = this {
             let eof = !stream.state.readable();
-            let (io, session) = stream.get_mut();
+            let (io, session) = (&mut stream.io, &mut stream.session);
             let mut stream = Stream::new(io, session).set_eof(eof);
 
             if stream.session.is_handshaking() {