Update docs

README.md

@@ -12,7 +12,7 @@ HTTPS, and charset decoding.
 Ureq is in pure Rust for safety and ease of understanding. It avoids using
 `unsafe` directly. It [uses blocking I/O][blocking] instead of async I/O, because that keeps
 the API simple and and keeps dependencies to a minimum. For TLS, ureq uses
-[rustls].
+[rustls] or [native-tls](https://docs.rs/native-tls/).
 
 Version 2.0.0 was released recently and changed some APIs. See the [changelog] for details.
 
@@ -211,6 +211,34 @@ fn proxy_example_2() -> std::result::Result<(), ureq::Error> {
 }
 ```
 
+## HTTPS / TLS / SSL
+
+By default, ureq uses rustls. You can add native-tls support by enableing the native-tls feature
+and calling AgentBuilder::tls_connector():
+
+```rust
+  use ureq::Agent;
+
+  let agent = ureq::AgentBuilder::new()
+      .tls_connector(native_tls::TlsConnector::new())
+      .build();
+```
+
+You might want to use native-tls if rustls is not supported on your platform, or if you need to
+interoperate with servers that only support less-secure ciphersuites and/or TLS versions older
+than 1.2. You can turn off TLS support entirely with `--no-default-features`.
+
+### Trusted Roots
+
+When you use rustls, ureq defaults to trusting [webpki-roots](https://docs.rs/webpki-roots/), a
+copy of the Mozilla Root program that is bundled into your program (and so won't update if your
+program isn't updated). You can alternately configure
+[rustls-native-certs](https://docs.rs/rustls-native-certs/) which extracts the roots from your
+OS' trust store. That means it will update when your OS is updated, and also that it will
+include locally installed roots.
+
+When you use native-tls, ureq will use your OS' certificate verifier and root store.
+
 ## Blocking I/O for simplicity
 
 Ureq uses blocking I/O rather than Rust's newer [asynchronous (async) I/O][async]. Async I/O

src/agent.rs

@@ -467,7 +467,9 @@ impl AgentBuilder {
         self
     }
 
-    /// Set the TLS client config to use for the connection. See [`ClientConfig`](https://docs.rs/rustls/latest/rustls/struct.ClientConfig.html).
+    /// Use rustls for connections from this agent and set the
+    /// [`rustls::ClientConfig`](https://docs.rs/rustls/0.19.1/rustls/struct.ClientConfig.html)
+    /// to use. Overrides any previous calls to [AgentBuilder::tls_connector]
     ///
     /// Example:
     /// ```
@@ -487,8 +489,9 @@ impl AgentBuilder {
         self
     }
 
-    /// Set the [native_tls::TlsConnector](https://docs.rs/native-tls/0.2.7/native_tls/struct.TlsConnector.html)
-    /// to use for the connection.
+    /// Use native-tls for connections from this agent and set the
+    /// [`native_tls::TlsConnector`](https://docs.rs/native-tls/0.2.7/native_tls/struct.TlsConnector.html)
+    /// to use. Overrides any previous calls to [AgentBuilder::tls_config].
     ///
     /// Example:
     /// ```

src/header.rs

@@ -64,7 +64,7 @@ impl fmt::Display for HeaderLine {
 
 #[derive(Clone, PartialEq)]
 /// Wrapper type for a header field.
-/// https://tools.ietf.org/html/rfc7230#section-3.2
+/// <https://tools.ietf.org/html/rfc7230#section-3.2>
 pub struct Header {
     // Line contains the unmodified bytes of single header field.
     // It does not contain the final CRLF.

src/lib.rs

@@ -17,7 +17,7 @@
 //! Ureq is in pure Rust for safety and ease of understanding. It avoids using
 //! `unsafe` directly. It [uses blocking I/O][blocking] instead of async I/O, because that keeps
 //! the API simple and and keeps dependencies to a minimum. For TLS, ureq uses
-//! [rustls].
+//! [rustls] or [native-tls](https://docs.rs/native-tls/).
 //!
 //! Version 2.0.0 was released recently and changed some APIs. See the [changelog] for details.
 //!
@@ -234,6 +234,38 @@
 //! # fn main() {}
 //! ```
 //!
+//! # HTTPS / TLS / SSL
+//!
+//! By default, ureq uses rustls. You can add native-tls support by enableing the native-tls feature
+//! and calling AgentBuilder::tls_connector():
+//!
+//! ```no_run
+//! # fn main() -> std::result::Result<(), ureq::Error> {
+//! # ureq::is_test(true);
+//!   use ureq::Agent;
+//!
+//!   let agent = ureq::AgentBuilder::new()
+//!       .tls_connector(native_tls::TlsConnector::new())
+//!       .build();
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! You might want to use native-tls if rustls is not supported on your platform, or if you need to
+//! interoperate with servers that only support less-secure ciphersuites and/or TLS versions older
+//! than 1.2. You can turn off TLS support entirely with `--no-default-features`.
+//!
+//! ## Trusted Roots
+//!
+//! When you use rustls, ureq defaults to trusting [webpki-roots](https://docs.rs/webpki-roots/), a
+//! copy of the Mozilla Root program that is bundled into your program (and so won't update if your
+//! program isn't updated). You can alternately configure
+//! [rustls-native-certs](https://docs.rs/rustls-native-certs/) which extracts the roots from your
+//! OS' trust store. That means it will update when your OS is updated, and also that it will
+//! include locally installed roots.
+//!
+//! When you use native-tls, ureq will use your OS' certificate verifier and root store.
+//!
 //! # Blocking I/O for simplicity
 //!
 //! Ureq uses blocking I/O rather than Rust's newer [asynchronous (async) I/O][async]. Async I/O