Update documentation for tokio-boring

This also adds an `examples/` directory, to make sure the example in the readme doesn't get out of
date.

tokio-boring/Cargo.toml

@@ -19,3 +19,4 @@ tokio = "1"
 [dev-dependencies]
 futures = "0.3"
 tokio = { version = "1", features = ["full"] }
+anyhow = "1"

tokio-boring/README.md

@@ -13,18 +13,37 @@ First, add this to your `Cargo.toml`:
 tokio-boring = "1.0.0"
 ```
 
-Next, add this to your crate:
+Then, use either `accept` or `connect` as appropriate.
 
 ```rust
-use tokio_boring::{SslConnectorExt, SslAcceptorExt};
+use boring::ssl;
+use tokio::net::TcpListener;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let listener = TcpListener::bind("127.0.0.1:8080").await?;
+    let (tcp_stream, _addr) = listener.accept().await?;
+
+    let server = ssl::SslMethod::tls_server();
+    let mut ssl_builder = boring::ssl::SslAcceptor::mozilla_modern(server)?;
+    ssl_builder.set_default_verify_paths()?;
+    ssl_builder.set_verify(ssl::SslVerifyMode::PEER);
+    let acceptor = ssl_builder.build();
+    let _ssl_stream = tokio_boring::accept(&acceptor, tcp_stream).await?;
+    Ok(())
+}
 ```
 
-This crate provides two extension traits, `SslConnectorExt` and
+This library is an implementation of TLS streams using BoringSSL for
-`SslAcceptorExt`, which augment the functionality provided by the [`boring` crate](https://github.com/cloudflare/boring).
+negotiating the connection. Each TLS stream implements the `Read` and
-These extension traits provide the ability to connect a stream
+`Write` traits to interact and interoperate with the rest of the futures I/O
-asynchronously and accept a socket asynchronously. Configuration of BoringSSL
+ecosystem. Client connections initiated from this crate verify hostnames
-parameters is still done through the support in the [`boring` crate](https://github.com/cloudflare/boring).
+automatically and by default.
 
+`tokio-boring` exports this ability through [`accept`] and [`connect`]. `accept` should
+be used by servers, and `connect` by clients. These augment the functionality provided by the
+[`boring`] crate, on which this crate is built. Configuration of TLS parameters is still
+primarily done through the [`boring`] crate.
 
 # License
 

tokio-boring/examples/simple-async.rs

@@ -0,0 +1,16 @@
+use boring::ssl;
+use tokio::net::TcpListener;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let listener = TcpListener::bind("127.0.0.1:8080").await?;
+    let (tcp_stream, _addr) = listener.accept().await?;
+
+    let server = ssl::SslMethod::tls_server();
+    let mut ssl_builder = boring::ssl::SslAcceptor::mozilla_modern(server)?;
+    ssl_builder.set_default_verify_paths()?;
+    ssl_builder.set_verify(ssl::SslVerifyMode::PEER);
+    let acceptor = ssl_builder.build();
+    let _ssl_stream = tokio_boring::accept(&acceptor, tcp_stream).await?;
+    Ok(())
+}

tokio-boring/src/lib.rs

@@ -6,11 +6,10 @@
 //! ecosystem. Client connections initiated from this crate verify hostnames
 //! automatically and by default.
 //!
-//! This crate primarily exports this ability through two extension traits,
+//! `tokio-boring` exports this ability through [`accept`] and [`connect`]. `accept` should
-//! `SslConnectorExt` and `SslAcceptorExt`. These traits augment the
+//! be used by servers, and `connect` by clients. These augment the functionality provided by the
-//! functionality provided by the [`boring` crate](https://github.com/cloudflare/boring) crate,
+//! [`boring`] crate, on which this crate is built. Configuration of TLS parameters is still
-//! on which this crate is built. Configuration of TLS parameters is still primarily done through
+//! primarily done through the [`boring`] crate.
-//! the [`boring` crate](https://github.com/cloudflare/boring)
 #![warn(missing_docs)]
 
 use boring::ssl::{