From 9a2149b43dc70dd2cc934e504500fded64f0c809 Mon Sep 17 00:00:00 2001
From: Sergio Benitez <sb@sergio.bz>
Date: Tue, 21 Jul 2020 11:53:45 -0700
Subject: [PATCH] Test guide and README using stable 'doc_comment'.

---
 README.md                           |  2 +-
 core/codegen/src/bang/test_guide.rs | 19 ++++++-------------
 site/guide/3-overview.md            | 13 ++++++++-----
 site/tests/Cargo.toml               |  3 ++-
 site/tests/src/lib.rs               | 11 ++++++++---
 5 files changed, 25 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index f41f5cd4..53f4934b 100644
--- a/README.md
+++ b/README.md
@@ -77,7 +77,7 @@ Rocket ships with an extensive number of examples in the `examples/` directory
 which can be compiled and run with Cargo. For instance, the following sequence
 of commands builds and runs the `Hello, world!` example:
 
-```
+```sh
 cd examples/hello_world
 cargo run
 ```
diff --git a/core/codegen/src/bang/test_guide.rs b/core/codegen/src/bang/test_guide.rs
index 906d1ad2..194d41e7 100644
--- a/core/codegen/src/bang/test_guide.rs
+++ b/core/codegen/src/bang/test_guide.rs
@@ -7,21 +7,17 @@ use devise::proc_macro2::TokenStream;
 
 pub fn _macro(input: proc_macro::TokenStream) -> devise::Result<TokenStream> {
     let root_glob = syn::parse::<LitStr>(input.into())?;
-    let modules = entry_to_modules(&root_glob)
+    let tests = entry_to_tests(&root_glob)
         .map_err(|e| root_glob.span().error(format!("failed to read: {}", e)))?;
 
-    Ok(quote_spanned!(root_glob.span() =>
-        #[allow(dead_code)]
-        #[allow(non_camel_case_types)]
-        mod test_site_guide { #(#modules)* }
-    ).into())
+    Ok(quote!(#(#tests)*))
 }
 
-fn entry_to_modules(root_glob: &LitStr) -> Result<Vec<TokenStream>, Box<dyn Error>> {
+fn entry_to_tests(root_glob: &LitStr) -> Result<Vec<TokenStream>, Box<dyn Error>> {
     let manifest_dir = std::env::var("CARGO_MANIFEST_DIR").expect("MANIFEST_DIR");
     let full_glob = Path::new(&manifest_dir).join(&root_glob.value()).display().to_string();
 
-    let mut modules = vec![];
+    let mut tests = vec![];
     for path in glob::glob(&full_glob).map_err(Box::new)? {
         let path = path.map_err(Box::new)?;
         let name = path.file_name()
@@ -32,11 +28,8 @@ fn entry_to_modules(root_glob: &LitStr) -> Result<Vec<TokenStream>, Box<dyn Erro
 
         let ident = Ident::new(&name, root_glob.span());
         let full_path = Path::new(&manifest_dir).join(&path).display().to_string();
-        modules.push(quote_spanned!(root_glob.span() =>
-            #[doc(include = #full_path)]
-            struct #ident;
-        ))
+        tests.push(quote_spanned!(root_glob.span() => doc_comment::doctest!(#full_path, #ident);))
     }
 
-    Ok(modules)
+    Ok(tests)
 }
diff --git a/site/guide/3-overview.md b/site/guide/3-overview.md
index 55e2379b..251b424d 100644
--- a/site/guide/3-overview.md
+++ b/site/guide/3-overview.md
@@ -251,13 +251,16 @@ stalls, or sometimes even deadlocks can occur.
 
   ```rust
   # #[macro_use] extern crate rocket;
+  use std::io;
   use rocket::tokio::task::spawn_blocking;
+  use rocket::response::Debug;
 
   #[get("/blocking_task")]
-  async fn blocking_task() -> Vec<u8> {
-      // In a real application, we would use rocket::response::NamedFile
-      spawn_blocking(|| {
-          std::fs::read("data.txt").expect("failed to read file")
-      }).await.unwrap()
+  async fn blocking_task() -> Result<Vec<u8>, Debug<io::Error>> {
+      // In a real app, we'd use rocket::response::NamedFile or tokio::fs::File.
+      let io_result = spawn_blocking(|| std::fs::read("data.txt")).await
+        .map_err(|join_err| io::Error::new(io::ErrorKind::Interrupted, join_err))?;
+
+      Ok(io_result?)
   }
   ```
diff --git a/site/tests/Cargo.toml b/site/tests/Cargo.toml
index 1f36db1c..004d6de4 100644
--- a/site/tests/Cargo.toml
+++ b/site/tests/Cargo.toml
@@ -5,8 +5,9 @@ workspace = "../../"
 edition = "2018"
 publish = false
 
-[dependencies]
+[dev-dependencies]
 rocket = { path = "../../core/lib" }
+doc-comment = "0.3"
 rocket_contrib = { path = "../../contrib/lib", features = ["json", "tera_templates", "diesel_sqlite_pool"] }
 serde = { version = "1.0", features = ["derive"] }
 rand = "0.7"
diff --git a/site/tests/src/lib.rs b/site/tests/src/lib.rs
index 5fcd6198..17c9d60d 100644
--- a/site/tests/src/lib.rs
+++ b/site/tests/src/lib.rs
@@ -1,4 +1,9 @@
-#![cfg_attr(test, feature(external_doc))]
+#[cfg(any(test, doctest))]
+mod site_guide {
+    rocket::rocket_internal_guide_tests!("../guide/*.md");
+}
 
-#[cfg(test)]
-rocket::rocket_internal_guide_tests!("../guide/*.md");
+#[cfg(any(test, doctest))]
+mod readme {
+    doc_comment::doctest!("../../../README.md", readme);
+}