arti-hyper: Expand docs

1 files changed, 15 insertions, 1 deletions

diff --git a/crates/arti-hyper/src/lib.rs b/crates/arti-hyper/src/lib.rs
index 80dd5baf1..643a52f07 100644
--- a/crates/arti-hyper/src/lib.rs
+++ b/crates/arti-hyper/src/lib.rs
@@ -91,9 +91,15 @@ impl tor_error::HasKind for ConnectionError {
     }
 }
 
-/// A `hyper` connector to proxy HTTP connections via the Tor network, using Arti.
+/// **Main entrypoint**: `hyper` connector to make HTTP\[S] connections via Tor, using Arti.
+///
+/// An `ArtiHttpConnector` combines an Arti Tor client, and a TLS implementation,
+/// in a form that can be provided to hyper
+/// (e.g. to [`hyper::client::Builder`]'s `build` method)
+/// so that hyper can speak HTTP and HTTPS to origin servers via Tor.
 ///
 /// TC is the TLS to used *across* Tor to connect to the origin server.
+/// For example, it could be a [`tls_api_native_tls::TlsConnector`].
 /// This is a different Rust type to the TLS used *by* Tor to connect to relays etc.
 /// It might even be a different underlying TLS implementation
 /// (although that is usually not a particularly good idea).
@@ -124,6 +130,14 @@ impl<R: Runtime, TC: TlsConn> ArtiHttpConnector<R, TC> {
 
 /// Wrapper type that makes an Arti `DataStream` implement necessary traits to be used as
 /// a `hyper` connection object (mainly `Connection`).
+///
+/// This might represent a bare HTTP connection across Tor,
+/// or it might represent an HTTPS connection through Tor to an origin server,
+/// `TC::TlsStream` as the TLS layer.
+///
+/// An `ArtiHttpConnection` is constructed by hyper's use of the [`ArtiHttpConnector`]
+/// implementation of [`hyper::service::Service`],
+/// and then used by hyper as the transport for hyper's HTTP implementation.
 #[pin_project]
 pub struct ArtiHttpConnection<TC: TlsConn> {
     /// The stream