Completed review

Author: AndyGauge

CONTRIBUTING.md

@@ -51,9 +51,9 @@ cargo test
 
 This project is intended to be simple to contribute to, and to always
 have obvious next work items available. If at any time there is not
-something obvious to contribute, that is a bug. Please ask for
-assistance on the [libz blitz] thread, or email Brian Anderson
-directly ([email protected]).
+something obvious to contribute, that is a bug. Feel free to ask for
+additional support at the
+[Rust Ecosystem Working Group](https://gitter.im/rust-lang/WG-ecosystem).
 
 The development process for the cookbook is presently oriented around
 crates: we decide which crates to represent in the cookbook, then come
@@ -146,16 +146,18 @@ something a typical Rust user typically wants to do.
 #### Description
 
 Describe traits imported and the methods used. Think about what information
-supports the use case and might not be obvious to someone new. Keep the 
-description to 1-4 sentences, avoiding explanations outside the scope of the 
+supports the use case and might not be obvious to someone new. Keep the
+description to 1-4 sentences, avoiding explanations outside the scope of the
 code sample.
 
-Use third person narative of the code execution, taking the opportunity
-to link to API documentation.  Hyperlink all references to APIs, either 
+Use third person narrative of the code execution, taking the opportunity
+to link to API documentation.  Always use
+[active voice](https://www.plainlanguage.gov/guidelines/conversational/use-active-voice/).
+Hyperlink all references to APIs, either
 on doc.rust-lang.org/std or docs.rs, and style them as `code`.  Use
 wildcard version specifiers for crate links.
 
-Any requirements to execute the code that are not apparent, such as 
+Any requirements to execute the code that are not apparent, such as
 passing environment flags, or configuring `Cargo.toml` should be added
 after the code sample.
 
@@ -164,8 +166,8 @@ after the code sample.
 > distribution, then sample from that distribution using
 > [`Distribution::sample`] with help of a random-number
 > generator [`rand::Rng`].
-> 
-> The [distributions available are documented here][rand-distributions]. 
+>
+> The [distributions available are documented here][rand-distributions].
 > An example using the [`Normal`] distribution is shown below.
 
 [uniform distribution]: https://en.wikipedia.org/wiki/Uniform_distribution_(continuous)
@@ -190,11 +192,11 @@ error handling correctly and propagate errors with `?` (not `try!`, `urwrap`, or
 `expect`). If there is no need for error handling in the example, prefer `main()`.
 
 Avoid glob imports (`*`), even for preludes, so that users can see what
-traits are called. (Some crates might consider using glob imports for preludes 
+traits are called. (Some crates might consider using glob imports for preludes
 best practice, making this awkward.)
 
 Examples should be simple and obvious enough that an experienced dev
-do not need comments. 
+do not need comments.
 
 Examples should compile without warnings, clippy lint warnings, or panics.
 The code should be formatted by rustfmt.  Hide all error boilerplate and
@@ -206,9 +208,9 @@ explanation in the description.
 
 > ```rust
 > extern crate rand;
-> 
+>
 > use rand::distributions::{Normal, Distribution};
-> 
+>
 > fn main() {
 >    let mut rng = rand::thread_rng();
 >    let normal = Normal::new(2.0, 3.0);

src/cli/arguments/clap-basic.md

@@ -17,7 +17,6 @@ extern crate clap;
 use clap::{Arg, App};
 
 fn main() {
-    // Define command line arguments.
     let matches = App::new("My Test Program")
         .version("0.1.0")
         .author("Hackerman Jones <[email protected]>")
@@ -34,11 +33,9 @@ fn main() {
                  .help("Five less than your favorite number"))
         .get_matches();
 
-    // Get value for file, or default to 'input.txt'.
     let myfile = matches.value_of("file").unwrap_or("input.txt");
     println!("The file passed is: {}", myfile);
 
-    // Get value for num if present, and try parsing it as i32.
     let num_str = matches.value_of("num");
     match num_str {
         None => println!("No idea what your favorite number is."),

src/compression/tar/tar-decompress.md

@@ -26,13 +26,9 @@ use tar::Archive;
 fn run() -> Result<()> {
     let path = "archive.tar.gz";
 
-    // Open a compressed tarball
     let tar_gz = File::open(path)?;
-    // Decompress it
     let tar = GzDecoder::new(tar_gz);
-    // Load the archive from the tarball
     let mut archive = Archive::new(tar);
-    // Unpack the archive inside curent working directory
     archive.unpack(".")?;
 
     Ok(())

src/compression/tar/tar-strip-prefix.md

@@ -34,7 +34,6 @@ fn run() -> Result<()> {
         .entries()?
         .filter_map(|e| e.ok())
         .map(|mut entry| -> Result<PathBuf> {
-            // Need to get owned data to break the borrow loop
             let path = entry.path()?.strip_prefix(prefix)?.to_owned();
             entry.unpack(&path)?;
             Ok(path)

src/concurrency.md

@@ -12,8 +12,6 @@
 | [Sort a vector in parallel][ex-rayon-parallel-sort] | [![rayon-badge]][rayon] [![rand-badge]][rand] | [![cat-concurrency-badge]][cat-concurrency] |
 | [Map-reduce in parallel][ex-rayon-map-reduce] | [![rayon-badge]][rayon] | [![cat-concurrency-badge]][cat-concurrency] |
 | [Generate jpg thumbnails in parallel][ex-rayon-thumbnails] | [![rayon-badge]][rayon] [![glob-badge]][glob] [![image-badge]][image] | [![cat-concurrency-badge]][cat-concurrency][![cat-filesystem-badge]][cat-filesystem] |
-=======
->>>>>>> 4e55642... merge artifacts removed
 
 
 [ex-crossbeam-spawn]: concurrency/threads.html#spawn-a-short-lived-thread

src/concurrency/parallel/rayon-any-all.md

@@ -12,17 +12,17 @@ use rayon::prelude::*;
 fn main() {
     let mut vec = vec![2, 4, 6, 8];
 
-    assert!(!vec.par_iter().any(|n| (*n % 2) != 0)); // None are odd.
-    assert!(vec.par_iter().all(|n| (*n % 2) == 0)); // All are even.
-    assert!(!vec.par_iter().any(|n| *n > 8 )); // None are greater than 8.
-    assert!(vec.par_iter().all(|n| *n <= 8 )); // All are less than or equal to 8.
+    assert!(!vec.par_iter().any(|n| (*n % 2) != 0));
+    assert!(vec.par_iter().all(|n| (*n % 2) == 0));
+    assert!(!vec.par_iter().any(|n| *n > 8 ));
+    assert!(vec.par_iter().all(|n| *n <= 8 ));
 
     vec.push(9);
 
-    assert!(vec.par_iter().any(|n| (*n % 2) != 0)); // At least 1 is odd.
-    assert!(!vec.par_iter().all(|n| (*n % 2) == 0)); // Not all are even.
-    assert!(vec.par_iter().any(|n| *n > 8 )); // At least 1 is greater than 8.
-    assert!(!vec.par_iter().all(|n| *n <= 8 )); // Not all are less than or equal to 8.
+    assert!(vec.par_iter().any(|n| (*n % 2) != 0));
+    assert!(!vec.par_iter().all(|n| (*n % 2) == 0));
+    assert!(vec.par_iter().any(|n| *n > 8 ));
+    assert!(!vec.par_iter().all(|n| *n <= 8 )); 
 }
 ```
 

src/concurrency/parallel/rayon-iter-mut.md

@@ -13,9 +13,7 @@ use rayon::prelude::*;
 
 fn main() {
     let mut arr = [0, 7, 9, 11];
-
     arr.par_iter_mut().for_each(|p| *p -= 1);
-
     println!("{:?}", arr);
 }
 ```

src/concurrency/parallel/rayon-thumbnails.md

@@ -32,8 +32,6 @@ use rayon::prelude::*;
 # }
 
 fn run() -> Result<()> {
-    // find all files in current directory that have a .jpg extension
-    // use the default MatchOptions so the search is case insensitive
     let options: MatchOptions = Default::default();
     let files: Vec<_> = glob_with("*.jpg", &options)?
         .filter_map(|x| x.ok())
@@ -63,8 +61,6 @@ fn run() -> Result<()> {
     Ok(())
 }
 
-/// Resize `original` to have a maximum dimension of `longest_edge` and save the
-/// resized image to the `thumb_dir` folder
 fn make_thumbnail<PA, PB>(original: PA, thumb_dir: PB, longest_edge: u32) -> Result<()>
 where
     PA: AsRef<Path>,

src/concurrency/thread/crossbeam-spawn.md

@@ -21,7 +21,6 @@ fn main() {
 }
 
 fn find_max(arr: &[i32], start: usize, end: usize) -> i32 {
-    // Perform sequential computation if there are only a few elements.
     const THRESHOLD: usize = 2;
     if end - start <= THRESHOLD {
         return *arr.iter().max().unwrap();

src/concurrency/thread/global-mut-state.md

@@ -24,23 +24,19 @@ lazy_static! {
 }
 
 fn insert(fruit: &str) -> Result<()> {
-    // acquire exclusive access
     let mut db = FRUIT.lock().map_err(|_| "Failed to acquire MutexGuard")?;
     db.push(fruit.to_string());
     Ok(())
-    // release exclusive access
 }
 
 fn run() -> Result<()> {
     insert("apple")?;
     insert("orange")?;
     insert("peach")?;
     {
-        // acquire access
         let db = FRUIT.lock().map_err(|_| "Failed to acquire MutexGuard")?;
 
         db.iter().enumerate().for_each(|(i, item)| println!("{}: {}", i, item));
-        // release access
     }
     insert("grape")?;
     Ok(())

src/concurrency/thread/threadpool-fractal.md

@@ -93,7 +93,6 @@ fn run() -> Result<()> {
     let mut img = ImageBuffer::new(width, height);
     let iterations = 300;
 
-    // constants to tweak for appearance
     let c = Complex::new(-0.8, 0.156);
 
     let pool = ThreadPool::new(num_cpus::get());

src/concurrency/thread/threadpool-walk.md

@@ -59,7 +59,6 @@ fn run() -> Result<()> {
 
     let (tx, rx) = channel();
 
-    // Look in the current directory.
     for entry in WalkDir::new("/home/user/Downloads")
         .follow_links(true)
         .into_iter()

src/cryptography/encryption/pbkdf2.md

@@ -30,11 +30,9 @@ fn run() -> Result<()> {
   const N_ITER: u32 = 100_000;
   let rng = rand::SystemRandom::new();
 
-  // Generate salt
   let mut salt = [0u8; CREDENTIAL_LEN];
   rng.fill(&mut salt)?;
 
-  // Hash password
   let password = "Guess Me If You Can!";
   let mut pbkdf2_hash = [0u8; CREDENTIAL_LEN];
   pbkdf2::derive(
@@ -47,7 +45,6 @@ fn run() -> Result<()> {
   println!("Salt: {}", HEXUPPER.encode(&salt));
   println!("PBKDF2 hash: {}", HEXUPPER.encode(&pbkdf2_hash));
 
-  // Verify hash with correct password and wrong password
   let should_succeed = pbkdf2::verify(
       &digest::SHA512,
       N_ITER,

src/cryptography/hashing/sha-digest.md

@@ -48,7 +48,6 @@ fn run() -> Result<()> {
     let reader = BufReader::new(input);
     let digest = sha256_digest(reader)?;
 
-    // digest.as_ref() provides the digest as a byte slice: &[u8]
     println!("SHA-256 digest is {}", HEXUPPER.encode(digest.as_ref()));
 
     Ok(())

src/data_structures/custom/bitfield.md

@@ -25,8 +25,7 @@ bitflags! {
 
 impl MyFlags {
     pub fn clear(&mut self) -> &mut MyFlags {
-        self.bits = 0;  // The `bits` field can be accessed from within the
-                        // same module where the `bitflags!` macro was invoked.
+        self.bits = 0;  
         self
     }
 }
@@ -40,15 +39,14 @@ impl fmt::Display for MyFlags {
 fn main() {
     let e1 = MyFlags::FLAG_A | MyFlags::FLAG_C;
     let e2 = MyFlags::FLAG_B | MyFlags::FLAG_C;
-    assert_eq!((e1 | e2), MyFlags::FLAG_ABC);   // union
-    assert_eq!((e1 & e2), MyFlags::FLAG_C);     // intersection
-    assert_eq!((e1 - e2), MyFlags::FLAG_A);     // set difference
-    assert_eq!(!e2, MyFlags::FLAG_A);           // set complement
+    assert_eq!((e1 | e2), MyFlags::FLAG_ABC);   
+    assert_eq!((e1 & e2), MyFlags::FLAG_C);    
+    assert_eq!((e1 - e2), MyFlags::FLAG_A);    
+    assert_eq!(!e2, MyFlags::FLAG_A);           
 
     let mut flags = MyFlags::FLAG_ABC;
     assert_eq!(format!("{}", flags), "00000000000000000000000000000111");
     assert_eq!(format!("{}", flags.clear()), "00000000000000000000000000000000");
-    // Debug trait is automatically derived for the MyFlags through `bitflags!`
     assert_eq!(format!("{:?}", MyFlags::FLAG_B), "FLAG_B");
     assert_eq!(format!("{:?}", MyFlags::FLAG_A | MyFlags::FLAG_B), "FLAG_A | FLAG_B");
 }

src/file/dir/duplicate-name.md

@@ -12,20 +12,14 @@ use std::collections::HashMap;
 use walkdir::WalkDir;
 
 fn main() {
-    // Counters indexed by filenames
     let mut filenames = HashMap::new();
 
-    // List recusively all files in the current directory filtering out
-    // directories and files not accessible (permission denied)
     for entry in WalkDir::new(".")
             .into_iter()
             .filter_map(Result::ok)
             .filter(|e| !e.file_type().is_dir()) {
-        // Get entry's filename
         let f_name = String::from(entry.file_name().to_string_lossy());
-        // Get or initialize the counter
         let counter = filenames.entry(f_name.clone()).or_insert(0);
-        // Update the counter
         *counter += 1;
 
         if *counter == 2 {

src/file/dir/find-file.md

@@ -22,17 +22,13 @@ use walkdir::WalkDir;
 # }
 
 fn run() -> Result<()> {
-    // List recusively all accessible files in the current directory
     for entry in WalkDir::new(".")
             .follow_links(true)
             .into_iter()
             .filter_map(|e| e.ok()) {
-        // Get entry's filename
         let f_name = entry.file_name().to_string_lossy();
-        // Get entry's modified time
         let sec = entry.metadata()?.modified()?;
 
-        // Print JSON files modified within the last day
         if f_name.ends_with(".json") && sec.elapsed()?.as_secs() < 86400 {
             println!("{}", f_name);
         }

src/file/dir/loops.md

@@ -17,7 +17,6 @@ use std::io;
 use std::path::{Path, PathBuf};
 use same_file::is_same_file;
 
-// Check this path against all of its parents
 fn contains_loop<P: AsRef<Path>>(path: P) -> io::Result<Option<(PathBuf, PathBuf)>> {
     let path = path.as_ref();
     let mut path_buf = path.to_path_buf();

src/file/dir/png.md

@@ -5,8 +5,8 @@
 Recursively find all PNG files in the current directory.
 In this case, the `**` pattern matches the current directory and all subdirectories.
 
-You can also use the `**` pattern for any directory, not just the current one.
-For example, `/media/**/*.png` would match all PNGs in `media` and it's subdirectories.
+Use the `**` pattern in any path portion. For example, `/media/**/*.png`
+matches all PNGs in `media` and it's subdirectories.
 
 ```rust,no_run
 # #[macro_use]

src/file/dir/sizes.md

@@ -3,8 +3,7 @@
 [![walkdir-badge]][walkdir] [![cat-filesystem-badge]][cat-filesystem]
 
 Recursion depth can be flexibly set by [`WalkDir::min_depth`] & [`WalkDir::max_depth`] methods.
-In this example we sum all file sizes to 3 subfolders depth, ignoring files in the root folder
-at the same time.
+Calculates sum of all file sizes to 3 subfolders depth, ignoring files in the root folder.
 
 ```rust
 extern crate walkdir;
@@ -16,10 +15,10 @@ fn main() {
         .min_depth(1)
         .max_depth(3)
         .into_iter()
-        .filter_map(|entry| entry.ok()) // Files, we have access to
-        .filter_map(|entry| entry.metadata().ok()) // Get metadata
-        .filter(|metadata| metadata.is_file()) // Filter out directories
-        .fold(0, |acc, m| acc + m.len()); // Accumulate sizes
+        .filter_map(|entry| entry.ok())
+        .filter_map(|entry| entry.metadata().ok())
+        .filter(|metadata| metadata.is_file())
+        .fold(0, |acc, m| acc + m.len());
 
     println!("Total size: {} bytes.", total_size);
 }

src/file/dir/skip-dot.md

@@ -2,9 +2,13 @@
 
 [![walkdir-badge]][walkdir] [![cat-filesystem-badge]][cat-filesystem]
 
-Uses [`filter_entry`] to descend recursively into entries passing the `is_not_hidden` predicate thus skipping hidden files and directories whereas [`Iterator::filter`] would be applied to each [`WalkDir::DirEntry`] even if the parent is a hidden directory.
+Uses [`filter_entry`] to descend recursively into entries passing the
+`is_not_hidden` predicate thus skipping hidden files and directories.
+ [`Iterator::filter`] applies to each [`WalkDir::DirEntry`] even if the parent
+ is a hidden directory.
 
-Root dir `"."` is yielded due to [`WalkDir::depth`] usage in `is_not_hidden` predicate.
+Root dir `"."` yields through [`WalkDir::depth`] usage in `is_not_hidden`
+predicate.
 
 ```rust,no_run
 extern crate walkdir;

src/file/read-write/memmap.md

@@ -33,7 +33,6 @@ fn run() -> Result<()> {
 
     let random_indexes = [0, 1, 2, 19, 22, 10, 11, 29];
     assert_eq!(&map[3..13], b"hovercraft");
-    // I'm using an iterator here to change indexes to bytes
     let random_bytes: Vec<u8> = random_indexes.iter()
         .map(|&idx| map[idx])
         .collect();