Update README.md files from rustdoc.

7 files changed, 173 insertions, 112 deletions

diff --git a/crates/arti-client/README.md b/crates/arti-client/README.md
index 79edfb95d..48160554d 100644
--- a/crates/arti-client/README.md
+++ b/crates/arti-client/README.md
@@ -5,65 +5,87 @@ High-level functionality for accessing the Tor network as a client.
 ## Overview
 
 The `arti-client` crate aims to provide a safe, easy-to-use API for
-applications that want to use Tor network to anonymize their
-traffic.  It hides most of the underlying detail, letting other
-crates decide how exactly to use the Tor crate.
+applications that want to use the Tor network to anonymize their traffic.
 
-This crate is part of
-[Arti](https://gitlab.torproject.org/tpo/core/arti/), a project to
-implement [Tor](https://www.torproject.org/) in Rust.
-It is the highest-level library crate in
-Arti, and the one that nearly all client-only programs should use.
-Most of its functionality is provided by lower-level crates in Arti.
+This crate is part of [Arti](https://gitlab.torproject.org/tpo/core/arti/),
+a project to implement [Tor](https://www.torproject.org/) in Rust. It is the
+highest-level library crate in Arti, and the one that nearly all client-only
+programs should use. Most of its functionality is provided by lower-level
+crates in Arti.
 
 ### ⚠ Warnings ⚠
 
-Note that Arti is a work in progress; although we've tried to
-write all the critical security components, you probably shouldn't
-use Arti in production until it's a bit more mature.
+Note that Arti is a work in progress; although we've tried to write all the
+critical security components, you probably shouldn't use Arti in production
+until it's a bit more mature.  (That said, now is a _great_ time to try
+our Arti on an experimental basis, so you can tell us what we need
+to fix between now and the 1.0.0 release.)
 
-Also note that all of the APIs for this crate, and for Arti in
-general, are not the least bit stable.  If you use this code,
-please expect your software to break on a regular basis.
+Also note that the APIs for this crate are not all yet
+completely stable.  We'll try not to break things without good
+reason, and we'll follow semantic versioning when we do, but
+please expect a certain amount of breakage between now and 1.0.0.
 
-## Using `arti-client`
-
-The main entry point for this crate is the [`TorClient`], an object that lets you make
-connections over the Tor network.
+The APIs exposed by lower-level crates in Arti are _even more
+unstable_; they will break more often than those from
+`arti-client`, for less reason.
 
-Calling [`TorClient::bootstrap`] establishes a connection to the Tor network, pulling in
-necessary state about network consensus as required. This state gets persisted to the
-locations specified in the [`TorClientConfig`].
+## Using `arti-client`
 
-A client can then be used to make connections over Tor with [`TorClient::connect`], which
-accepts anything implementing [`IntoTorAddr`]. This returns a [`DataStream`], an anonymized
-TCP stream type that implements [`AsyncRead`](futures::io::AsyncRead) and
-[`AsyncWrite`](futures::io::AsyncWrite), as well as the Tokio versions of those traits if
-the `tokio` crate feature is enabled.
+The main entry point for this crate is the [`TorClient`], an object that
+lets you make connections over the Tor network.
 
-The [`TorAddr`] type is intended to ensure that DNS lookups are done via the Tor network
-instead of locally. Doing local DNS resolution can leak information about which hostnames you're
-connecting to to your local DNS resolver (i.e. your ISP), so it's much better to let Arti
-do it for you to maintain privacy.
+### Connecting to Tor
 
-If you really want to connect to a raw IP address and know what you're doing, take a look at
-[`TorAddr::dangerously_from`] -- but be careful!
+Calling [`TorClient::create_bootstrapped`] establishes a connection to the Tor
+network, pulling in necessary state about network consensus as required.
+This state gets persisted to the locations specified in the
+[`TorClientConfig`].
 
-### Example: making connections over Tor
+(This method requires you to initialize the client in an `async fn`. Consider
+using the builder method, below, if that doesn't work for you.)
 
 ```rust
 // The client configuration describes how to connect to the Tor network,
 // and what directories to use for storing persistent state.
 let config = TorClientConfig::default();
-// Arti needs a handle to an async runtime in order to spawn tasks and use the
-// network. (See "Multiple runtime support" below.)
-let rt = tor_rtcompat::tokio::TokioNativeTlsRuntime::current()?;
 
 // Start the Arti client, and let it bootstrap a connection to the Tor network.
 // (This takes a while to gather the necessary directory information.
 // It uses cached information when possible.)
-let tor_client = TorClient::bootstrap(rt, config).await?;
+let tor_client = TorClient::create_bootstrapped(config).await?;
+```
+
+### Creating a client and connecting later
+
+You might wish to create a Tor client immediately, without waiting for it to bootstrap (or
+having to use an `await`). This can be done by making a [`TorClientBuilder`] with
+[`TorClient::builder`], and calling [`TorClientBuilder::create_unbootstrapped`].
+
+The returned client can be made to bootstrap when it is first used (the default), or not;
+see [`BootstrapBehavior`] for more details.
+
+```rust
+// Specifying `BootstrapBehavior::OnDemand` means the client will automatically
+// bootstrap when it is used. `Manual` exists if you'd rather have full control.
+let tor_client = TorClient::builder()
+    .bootstrap_behavior(BootstrapBehavior::OnDemand)
+    .create_unbootstrapped()?;
+```
+
+### Using the client
 
+A client can then be used to make connections over Tor with
+[`TorClient::connect`], which accepts anything implementing [`IntoTorAddr`].
+This returns a [`DataStream`], an anonymized TCP stream type that implements
+[`AsyncRead`](futures::io::AsyncRead) and
+[`AsyncWrite`](futures::io::AsyncWrite), as well as the Tokio versions of
+those traits if the `tokio` crate feature is enabled.
+
+### Example: making connections over Tor
+
+```rust
+#
 // Initiate a connection over Tor to example.com, port 80.
 let mut stream = tor_client.connect(("example.com", 80)).await?;
 
@@ -88,59 +110,57 @@ println!("{}", String::from_utf8_lossy(&buf));
 
 ### More advanced usage
 
-This version of Arti includes basic support for "stream isolation": the ability to ensure that
-different TCP connections ('streams') go over different Tor circuits (and thus different exit
-nodes, making them originate from different IP addresses).
+This version of Arti includes basic support for "stream isolation": the
+ability to ensure that different TCP connections ('streams') go over
+different Tor circuits (and thus different exit nodes, making them originate
+from different IP addresses).
 
-This is useful to avoid deanonymizing
-users by correlation: for example, you might want a Tor connection to your bank and a Tor
-connection to an online forum to use different circuits, to avoid the possibility of the two
+This is useful to avoid deanonymizing users by correlation: for example, you
+might want a Tor connection to your bank and a Tor connection to an online
+forum to use different circuits, to avoid the possibility of the two
 identities being linked by having the same source IP.
 
 Streams can be isolated in two ways:
 
-- by calling [`TorClient::isolated_client`], which returns a new [`TorClient`] whose streams
-  will use a different circuit
-- by generating [`IsolationToken`]s, and passing them in via [`StreamPrefs`] to
-  [`TorClient::connect`].
+- by calling [`TorClient::isolated_client`], which returns a new
+  [`TorClient`] whose streams will use a different circuit
+- by generating [`IsolationToken`]s, and passing them in via [`StreamPrefs`]
+  to [`TorClient::connect`].
 
 ## Multiple runtime support
 
-Arti uses the [`tor_rtcompat`] crate to support multiple asynchronous runtimes; currently,
-both [Tokio](https://tokio.rs) and [async-std](https://async.rs) are supported.
-
-Functions in this crate, like [`TorClient::bootstrap`],
-will expect a type that implements [`tor_rtcompat::Runtime`], which can be obtained:
+Arti uses the [`tor_rtcompat`] crate to support multiple asynchronous
+runtimes; currently, both [Tokio](https://tokio.rs) and
+[async-std](https://async.rs) are supported.
 
-- for Tokio:
-  - by calling [`tor_rtcompat::tokio::PreferredRuntime::current()`], if a Tokio reactor is already running
-  - by calling [`tor_rtcompat::tokio::PreferredRuntime::create()`], to start a new reactor if one is not
-    already running
-  - as above, but explicitly specifying [`TokioNativeTlsRuntime`](tor_rtcompat::tokio::TokioNativeTlsRuntime)
-    or [`TokioRustlsRuntime`](tor_rtcompat::tokio::TokioRustlsRuntime) in place of `PreferredRuntime`.
-- for async-std:
-  - by calling [`tor_rtcompat::async_std::PreferredRuntime::current()`], which will create a runtime or
-    retrieve the existing one, if one has already been started
-  - as above, but explicitly specifying [`AsyncStdNativeTlsRuntime`](tor_rtcompat::async_std::AsyncStdNativeTlsRuntime)
-    or [`AsyncStdRustlsRuntime`](tor_rtcompat::async_std::AsyncStdRustlsRuntime) in place of `PreferredRuntime`.
+The backend Arti uses for TCP connections ([`tor_rtcompat::TcpProvider`]) and for
+creating TLS sessions ([`tor_rtcompat::TlsProvider`]) is also configurable using
+this crate. This can be used to embed Arti in custom environments where you want
+lots of control over how it uses the network.
 
+[**View the `tor_rtcompat` crate documentation**](tor_rtcompat) for more about these features.
 
 ## Feature flags
 
-`tokio` -- (Default) Build with support for the Tokio backend.
-
-`async-std` -- Build with support for the `async_std` backend.
-
-`native-tls` (default), `rustls` -- Select TLS libraries to support. 
-
-`static` -- Link with static versions of your system dependencies,
-including sqlite and/or openssl.
-
-`experimental-api` -- Build with experimental, unstable API support.
-Note that these APIs are NOT covered by semantic versioning guarantees:
-we might break them or remove them between patch versions.
-
-`error_detail` -- Make the `TorError` type transparent, and expose the `Error` within.
-Note that the resulting APIs are not stable.
+* `tokio` (default) -- build with [Tokio](https://tokio.rs/) support
+* `native-tls` (default) -- build with the [native-tls](https://github.com/sfackler/rust-native-tls)
+  crate for TLS support
+* `async-std` -- build with [async-std](https://async.rs/) support
+* `rustls` -- build with the [rustls](https://github.com/rustls/rustls) crate for TLS support
+* `static` -- link with static versions of Arti's system dependencies, like SQLite and
+  OpenSSL (⚠ Warning ⚠: this feature will include a dependency on native-tls, even if you weren't
+  planning to use native-tls.  If you only want to build with a static sqlite library, enable the
+  `static-sqlite` feature.  We'll look for better solutions here in the future.)
+* `static-sqlite` -- link with a static version of sqlite.
+* `static-native-tls` -- link with a static version of `native-tls`. Enables `native-tls`.
+* `experimental-api` -- build with experimental, unstable API support. Note
+  that these APIs are NOT covered by semantic versioning guarantees: we might
+  break them or remove them between patch versions.
+* `error_detail` -- expose the `arti_client::Error` inner error type. Note
+  that this API is NOT covered by semantic versioning guarantees: we might
+  break it between patch versions.
+
+Note that flags `tokio`, `native-tls`, `async-std`, `rustls` and `static` will enable
+the flags of the same name on the [`tor_rtcompat`] crate.
 
 License: MIT OR Apache-2.0
diff --git a/crates/arti-config/README.md b/crates/arti-config/README.md
index a0e55728e..88cb29119 100644
--- a/crates/arti-config/README.md
+++ b/crates/arti-config/README.md
@@ -11,4 +11,12 @@ implement [Tor](https://www.torproject.org/) in Rust.
 It provides a client configuration tool using using `serde` and `config`,
 plus extra features defined here for convenience.
 
+## ⚠ Stability Warning ⚠
+
+The design of this crate, and of the configuration system for
+Arti, is likely to change significantly before the release of Arti
+1.0.0.  For more information see ticket [#285].
+
+[#285]: https://gitlab.torproject.org/tpo/core/arti/-/issues/285
+
 License: MIT OR Apache-2.0
diff --git a/crates/arti-hyper/README.md b/crates/arti-hyper/README.md
index 9861a3bdf..14fcb96e6 100644
--- a/crates/arti-hyper/README.md
+++ b/crates/arti-hyper/README.md
@@ -2,13 +2,12 @@
 
 High-level layer for making http(s) requests the Tor network as a client.
 
-## Feature flags
+This can be used by applications which embed Arti,
+and could also be used as an example of how to build on top of [`arti_client`].
 
-`experimental-api` -- Build with experimental, unstable API support.
-Note that these APIs are NOT covered by semantic versioning guarantees:
-we might break them or remove them between patch versions.
+There is an example program [`hyper.rs`] which uses `arti-hyper`
+to connect to Tor and make a single HTTP\[S] request.
 
-`native-tls` (default), `rustls` -- Select TLS libraries to use for Tor's purposes.
-(The end-to-end TLS to the origin server is separate, and handled via `tls-api`.)
+[`hyper.rs`]: <https://gitlab.torproject.org/tpo/core/arti/-/blob/main/crates/arti-hyper/examples/hyper.rs>
 
 License: MIT OR Apache-2.0
diff --git a/crates/arti/README.md b/crates/arti/README.md
index 22f60db8a..357521107 100644
--- a/crates/arti/README.md
+++ b/crates/arti/README.md
@@ -42,8 +42,22 @@ For an example see [`arti_defaults.toml`](./arti_defaults.toml).
 `async-std`: Use the async-std runtime library as our backend.
 This feature has no effect unless building with `--no-default-features`
 to disable tokio.
+`native-tls` -- Build with support for the `native_tls` TLS
+backend. (default)
 
-`static`: Try to link a single static binary.
+`rustls` -- Build with support for the `rustls` TLS backend.
+
+`static` -- Link with static versions of your system dependencies,
+including sqlite and/or openssl.  (⚠ Warning ⚠: this feature will
+include a dependency on native-tls, even if you weren't planning
+to use native-tls.  If you only want to build with a static sqlite
+library, enable the `static-sqlite` feature.  We'll look for
+better solutions here in the future.)
+
+`static-sqlite` -- Link with a static version of sqlite.
+
+`static-native-tls` -- Link with a static version of `native-tls`.
+Enables `native-tls`.
 
 ## Limitations
 
diff --git a/crates/tor-config/README.md b/crates/tor-config/README.md
index 4557bf939..272d795ab 100644
--- a/crates/tor-config/README.md
+++ b/crates/tor-config/README.md
@@ -10,4 +10,12 @@ implement [Tor](https://www.torproject.org/) in Rust.
 
 It provides low-level types for handling configuration values.
 
+## ⚠ Stability Warning ⚠
+
+The design of this crate, and of the configuration system for
+Arti, is likely to change significantly before the release of Arti
+1.0.0.  For more information see ticket [#285].
+
+[#285]: https://gitlab.torproject.org/tpo/core/arti/-/issues/285
+
 License: MIT OR Apache-2.0
diff --git a/crates/tor-error/README.md b/crates/tor-error/README.md
index 8fc396d0d..838255554 100644
--- a/crates/tor-error/README.md
+++ b/crates/tor-error/README.md
@@ -1,22 +1,11 @@
 # tor-error
 
-`tor-error`: Support for error handling in Tor and Ari
+`tor-error` -- Support for error handling in Tor and Ari
 
-## Overview
+Primarily, this crate provides the [`ErrorKind`] enum,
+and associated [`HasKind`] trait.
 
-This crate is part of
-[Arti](https://gitlab.torproject.org/tpo/core/arti/), a project to
-implement [Tor](https://www.torproject.org/) in Rust.
-
-Primarily, this crate provides the [`tor_error::ErrorKind`] enum,
-which can be used by an application embedding the Arti/Tor code to
-categorise errors so as to respond to them.
-
-You probably don't want to use this separately from the `tor-*` and `arti-*` crates.
-
-## Compile-time features
-
- * `backtrace`: Enables the capturing stack backtraces in internal errors,
-   (via a dependency on the `backtrace` crate).  Enabled by default.
+There is also some other miscellany, supporting error handling in
+crates higher up the dependency stack.
 
 License: MIT OR Apache-2.0
diff --git a/crates/tor-rtcompat/README.md b/crates/tor-rtcompat/README.md
index 5dbc06c67..7dace222c 100644
--- a/crates/tor-rtcompat/README.md
+++ b/crates/tor-rtcompat/README.md
@@ -1,6 +1,6 @@
 # tor-rtcompat
 
-Compatibility between different async runtimes for Arti
+Compatibility between different async runtimes for Arti.
 
 ## Overview
 
@@ -57,29 +57,52 @@ You can get a [`Runtime`] in several ways:
   * If you already have an asynchronous backend (for example, one
     that you built with tokio by running with
     `#[tokio::main]`), you can wrap it as a [`Runtime`] with
-    [`current_user_runtime()`].
+    [`PreferredRuntime::current()`].
 
   * If you want to construct a default runtime that you won't be
-    using for anything besides Arti, you can use [`create_runtime()`].
+    using for anything besides Arti, you can use [`PreferredRuntime::create()`].
+
+Both of the above methods use the "preferred runtime", which is usually Tokio.
+However, changing the set of Cargo features available can affect this; see
+[`PreferredRuntime`] for more.
 
   * If you want to use a runtime with an explicitly chosen backend,
     name its type directly as [`async_std::AsyncStdNativeTlsRuntime`],
     [`async_std::AsyncStdRustlsRuntime`], [`tokio::TokioNativeTlsRuntime`],
     or [`tokio::TokioRustlsRuntime`]. To construct one of these runtimes,
     call its `create()` method.  Or if you have already constructed a
-    tokio runtime that you want to use, you can wrap it as a
+    Tokio runtime that you want to use, you can wrap it as a
     [`Runtime`] explicitly with `current()`.
 
-## Cargo features
+## Advanced usage: implementing runtimes yourself
+
+You might want to implement some of the traits above (especially [`TcpProvider`] and
+[`TlsProvider`]) if you're embedding Arti, and want more control over the resources it uses.
+For example, you might want to perform actions when TCP connections open and close, replace the
+TLS stack with your own, or proxy TCP connections over your own custom transport.
 
-`tokio` -- (Default) Build with Tokio support.
+This can be more easily accomplished using the [`CompoundRuntime`] type, which lets you
+create a [`Runtime`] from various implementors of the various traits (which don't all need to
+be the same).
+
+See [`arti-client/examples/hook-tcp.rs`](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/crates/arti-client/examples/hook-tcp.rs)
+for a full example of this.
+
+## Cargo features
 
-`async-std` -- Build with async_std support.
+Features supported by this crate:
 
-`native-tls`, `rustls` -- Select TLS libraries to support. 
+* `tokio` -- build with [Tokio](https://tokio.rs/) support
+* `async-std` -- build with [async-std](https://async.rs/) support
+* `native-tls` --  build with the [native-tls](https://github.com/sfackler/rust-native-tls)
+  crate for TLS support
+* `static` -- link the native TLS library statically (enables the `vendored` feature of the
+  `native-tls` crate).
+* `rustls` -- build with the [rustls](https://github.com/rustls/rustls) crate for TLS support
 
-`static` -- Try to link with a static copy of our native TLS library,
-if possible.
+By default, *this* crate doesn't enable any features. However, you're almost certainly
+using this as part of the `arti-client` crate, which will enable `tokio` and `native-tls` in
+its default configuration.
 
 ## Design FAQ