From a3ef00526b312a71dad2d7d907e6d64791d75355 Mon Sep 17 00:00:00 2001
From: Manuel Cillero <manuel@cillero.es>
Date: Sat, 6 Aug 2022 13:12:56 +0200
Subject: [PATCH] =?UTF-8?q?Mejora=20documentaci=C3=B3n=20de=20bundle=5Fres?=
 =?UTF-8?q?ources=20[pagetop]?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 pagetop/build.rs    | 12 ++++++------
 pagetop/src/util.rs | 31 ++++++++++++++++---------------
 2 files changed, 22 insertions(+), 21 deletions(-)

diff --git a/pagetop/build.rs b/pagetop/build.rs
index 9e4b899a..92f494cf 100644
--- a/pagetop/build.rs
+++ b/pagetop/build.rs
@@ -7,13 +7,13 @@ fn main() -> std::io::Result<()> {
     bundle_resources("./static/bulmix", "bulmix")
 }
 
-/// This function is a simplified version of pagetop::util::bundle_resources().
+/// This function is a simplified version of `pagetop::util::bundle_resources()`.
 pub fn bundle_resources(from_dir: &str, with_name: &str) -> std::io::Result<()> {
-    let mut r = static_files::resource_dir(from_dir);
-    r.with_generated_filename(
+    let mut bundle = static_files::resource_dir(from_dir);
+    bundle.with_generated_filename(
         Path::new(std::env::var("OUT_DIR").unwrap().as_str()).join(format!("{}.rs", with_name)),
     );
-    r.with_module_name(format!("resources_{}", with_name));
-    r.with_generated_fn(format!("bundle_{}", with_name));
-    r.build()
+    bundle.with_module_name(format!("resources_{}", with_name));
+    bundle.with_generated_fn(format!("bundle_{}", with_name));
+    bundle.build()
 }
diff --git a/pagetop/src/util.rs b/pagetop/src/util.rs
index 4af209a5..e1aa44bc 100644
--- a/pagetop/src/util.rs
+++ b/pagetop/src/util.rs
@@ -26,7 +26,7 @@ pub type HashMapResources = std::collections::HashMap<&'static str, StaticResour
 /// pagetop = { ... }
 /// ```
 ///
-/// Add `build.rs` with call to bundle resources:
+/// Add `build.rs` with call to bundle resources (*guides* will be the magic word in this example):
 ///
 /// ```rust#ignore
 /// use pagetop::util::bundle_resources;
@@ -36,10 +36,7 @@ pub type HashMapResources = std::collections::HashMap<&'static str, StaticResour
 /// }
 /// ```
 ///
-/// This will create the resources file "guides.rs" in the standard output directory from files
-/// located at "./static" folder.
-///
-/// Optionally, you can also pass a function to filter the files in the "./static" folder that
+/// Optionally, you can pass a function to filter those files into the `./static` folder which
 /// should be included in the resources file:
 ///
 /// ```rust#ignore
@@ -51,20 +48,24 @@ pub type HashMapResources = std::collections::HashMap<&'static str, StaticResour
 ///
 /// fn except_css_dir(p: &Path) -> bool {
 ///     if let Some(parent) = p.parent() {
-///         ! matches!(parent.to_str(), Some("/css"))
+///         !matches!(parent.to_str(), Some("/css"))
 ///     }
 ///     true
 /// }
 /// ```
 ///
-/// Finally, a module called "resources_guides" will be compiled with your project. And the function
-/// to embed the generated HashMap resources collection in your code will be "bundle_guides":
+/// This will create a file called `guides.rs` where all output and intermediate artifacts are
+/// placed, see [OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html).
+///
+/// You don't need to access this file, just include it in your source code and a module called
+/// `resources_guides` will be added to your project. Use the function `bundle_guides` to embed the
+/// generated HashMap resources collection:
 ///
 /// ```rust#ignore
 /// use pagetop::prelude::*;
 ///
 /// include!(concat!(env!("OUT_DIR"), "/guides.rs"));
-/// static GUIDES: LazyStatic<HashMapResources> = LazyStatic::new(bundle_guides);
+/// static RESOURCES: LazyStatic<HashMapResources> = LazyStatic::new(bundle_guides);
 /// ```
 ///
 /// You can build more than one resources file to compile with your project.
@@ -73,16 +74,16 @@ pub fn bundle_resources(
     with_name: &str,
     filtering: Option<fn(p: &Path) -> bool>,
 ) -> std::io::Result<()> {
-    let mut r = static_files::resource_dir(from_dir);
-    r.with_generated_filename(
+    let mut bundle = static_files::resource_dir(from_dir);
+    bundle.with_generated_filename(
         Path::new(std::env::var("OUT_DIR").unwrap().as_str()).join(format!("{}.rs", with_name)),
     );
-    r.with_module_name(format!("resources_{}", with_name));
-    r.with_generated_fn(format!("bundle_{}", with_name));
+    bundle.with_module_name(format!("resources_{}", with_name));
+    bundle.with_generated_fn(format!("bundle_{}", with_name));
     if let Some(filter_files) = filtering {
-        r.with_filter(filter_files);
+        bundle.with_filter(filter_files);
     }
-    r.build()
+    bundle.build()
 }
 
 pub type Handler = u64;