From 034834212e73a2985b228d4ab5d490880e0f15fc Mon Sep 17 00:00:00 2001
From: Jacob Hoffman-Andrews <github@hoffman-andrews.com>
Date: Sat, 2 Dec 2023 11:05:40 -0800
Subject: [PATCH] doc: add example of how to use with rustls 0.22

Also, add documentation about how roots are compiled in and what that
means in practice.
---
 src/lib.rs       | 21 +++++++++++++++++----
 tests/codegen.rs | 23 ++++++++++++++++++-----
 2 files changed, 35 insertions(+), 9 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index db84e56..67e5a63 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,10 +1,23 @@
+//! A compiled-in copy of the root certificates trusted by Mozilla as of {:?}",
 //!
-//! This library is automatically generated from the Mozilla
-//! IncludedCACertificateReportPEMCSV report via ccadb.org. Don't edit it.
+//! To use this library with rustls 0.22:
 //!
-//! The generation is done deterministically so you can verify it
-//! yourself by inspecting and re-running the generation process.
+//! ```rust
+//! let mut root_store = rustls::RootCertStore {
+//!   roots: webpki_roots::TLS_SERVER_ROOTS.iter().cloned().collect(),
+//! };
+//! ```
 //!
+//! This library is suitable for use in applications that can always be recompiled and instantly deployed.
+//! For applications that are deployed to end-users and cannot be recompiled, or which need certification
+//! before deployment, consider a library that loads certificates at runtime, like
+//! [rustls-native-certs](https://docs.rs/rustls-native-certs).
+//
+// This library is automatically generated from the Mozilla
+// IncludedCACertificateReportPEMCSV report via ccadb.org. Don't edit it.
+//
+// The generation is done deterministically so you can verify it
+// yourself by inspecting and re-running the generation process.
 
 #![no_std]
 #![forbid(unsafe_code, unstable_features)]
diff --git a/tests/codegen.rs b/tests/codegen.rs
index 38ce893..beabf7c 100644
--- a/tests/codegen.rs
+++ b/tests/codegen.rs
@@ -375,13 +375,26 @@ impl From<&str> for TrustBits {
     }
 }
 
-const HEADER: &str = r#"//!
-//! This library is automatically generated from the Mozilla
-//! IncludedCACertificateReportPEMCSV report via ccadb.org. Don't edit it.
+const HEADER: &str = r#"//! A compiled-in copy of the root certificates trusted by Mozilla as of {:?}",
 //!
-//! The generation is done deterministically so you can verify it
-//! yourself by inspecting and re-running the generation process.
+//! To use this library with rustls 0.22:
 //!
+//! ```rust
+//! let mut root_store = rustls::RootCertStore {
+//!   roots: webpki_roots::TLS_SERVER_ROOTS.iter().cloned().collect(),
+//! };
+//! ```
+//!
+//! This library is suitable for use in applications that can always be recompiled and instantly deployed.
+//! For applications that are deployed to end-users and cannot be recompiled, or which need certification
+//! before deployment, consider a library that loads certificates at runtime, like
+//! [rustls-native-certs](https://docs.rs/rustls-native-certs).
+//
+// This library is automatically generated from the Mozilla
+// IncludedCACertificateReportPEMCSV report via ccadb.org. Don't edit it.
+//
+// The generation is done deterministically so you can verify it
+// yourself by inspecting and re-running the generation process.
 
 #![no_std]
 #![forbid(unsafe_code, unstable_features)]