Merge pull request #1189 from Xmasreturns/chapter_1_edits

Copy edits to chapter 1

Author: marioidival

src/hello.md

@@ -3,16 +3,16 @@
 This is the source code of the traditional Hello World program.
 
 ```rust,editable
-// This is a comment, and will be ignored by the compiler
+// This is a comment, and is ignored by the compiler
 // You can test this code by clicking the "Run" button over there ->
-// or if prefer to use your keyboard, you can use the "Ctrl + Enter" shortcut
+// or if you prefer to use your keyboard, you can use the "Ctrl + Enter" shortcut
 
 // This code is editable, feel free to hack it!
 // You can always return to the original code by clicking the "Reset" button ->
 
 // This is the main function
 fn main() {
-    // The statements here will be executed when the compiled binary is called
+    // Statements here are executed when the compiled binary is called
 
     // Print text to the console
     println!("Hello World!");

src/hello/comment.md

@@ -1,43 +1,43 @@
 # Comments
 
-Any program requires comments and indeed Rust supports
+Any program requires comments, and Rust supports
 a few different varieties:
 
 * *Regular comments* which are ignored by the compiler:
- - `// Line comments which go to the end of the line.`
- - `/* Block comments which go to the closing delimiter. */`
+   * `// Line comments which go to the end of the line.`
+   * `/* Block comments which go to the closing delimiter. */`
 * *Doc comments* which are parsed into HTML library
-[documentation][docs]:
- - `/// Generate library docs for the following item.`
- - `//! Generate library docs for the enclosing item.`
+  [documentation][docs]:
+   * `/// Generate library docs for the following item.`
+   * `//! Generate library docs for the enclosing item.`
 
 ```rust,editable
 fn main() {
     // This is an example of a line comment
-    // Notice how there are two slashes at the beginning of the line
-    // And that nothing written inside these will be read by the compiler
+    // There are two slashes at the beginning of the line
+    // And nothing written inside these will be read by the compiler
 
     // println!("Hello, world!");
 
     // Run it. See? Now try deleting the two slashes, and run it again.
 
     /* 
-     * This is another type of comment, the block comment. In general,
-     * the line comment is the recommended comment style however the
-     * block comment is extremely useful for temporarily disabling
-     * a large chunk of code. /* Block comments can be /* nested, */ */
-     * so it takes only a few keystrokes to comment out all the lines
+     * This is another type of comment, a block comment. In general,
+     * line comments are the recommended comment style. But
+     * block comments are extremely useful for temporarily disabling
+     * chunks of code. /* Block comments can be /* nested, */ */
+     * so it takes only a few keystrokes to comment out everything
      * in this main() function. /*/*/* Try it yourself! */*/*/
      */
 
     /*
-    Note, the previous column of `*` was entirely for style. There's
+    Note: The previous column of `*` was entirely for style. There's
     no actual need for it.
     */
 
-    // Observe how block comments allow easy expression manipulation
-    // which line comments do not. Deleting the comment delimiters
-    // will change the result:
+    // You can manipulate expressions more easily with block comments
+    // than with line comments. Try deleting the comment delimiters
+    // to change the result:
     let x = 5 + /* 90 + */ 5;
     println!("Is `x` 10 or 100? x = {}", x);
 }

src/hello/print.md

@@ -9,17 +9,17 @@ some of which include:
 * `eprint!`: same as `format!` but the text is printed to the standard error (io::stderr).
 * `eprintln!`: same as `eprint!`but a newline is appended.
 
-All parse text in the same fashion. A plus is that the formatting correctness will
-be checked at compile time.
+All parse text in the same fashion. As a plus, Rust checks formatting 
+correctness at compile time.
 
 ```rust,editable,ignore,mdbook-runnable
 fn main() {
     // In general, the `{}` will be automatically replaced with any
     // arguments. These will be stringified.
     println!("{} days", 31);
 
-    // Without a suffix, 31 becomes an i32. You can change what type 31 is,
-    // with a suffix.
+    // Without a suffix, 31 becomes an i32. You can change what type 31 is
+    // by providing a suffix.
 
     // There are various optional patterns this works with. Positional
     // arguments can be used.
@@ -41,12 +41,12 @@ fn main() {
     // You can pad numbers with extra zeroes. This will output "000001".
     println!("{number:>0width$}", number=1, width=6);
 
-    // It will even check to make sure the correct number of arguments are
+    // Rust even checks to make sure the correct number of arguments are
     // used.
     println!("My name is {0}, {1} {0}", "Bond");
     // FIXME ^ Add the missing argument: "James"
 
-    // Create a structure which contains an `i32`. Name it `Structure`.
+    // Create a structure named `Structure` which contains an `i32`.
     #[allow(dead_code)]
     struct Structure(i32);
 
@@ -64,7 +64,7 @@ of text. The base form of two important ones are listed below:
 * `fmt::Display`: Uses the `{}` marker. Format text in a more elegant, user
 friendly fashion.
 
-Here, `fmt::Display` was used because the std library provides implementations
+Here, we used `fmt::Display `because the std library provides implementations
 for these types. To print text for custom types, more steps are required.
 
 Implementing the `fmt::Display` trait automagically implements the
@@ -76,7 +76,7 @@ Implementing the `fmt::Display` trait automagically implements the
    error.
  * Add a `println!` macro that prints: `Pi is roughly 3.142` by controlling
    the number of decimal places shown. For the purposes of this exercise,
-   use `let pi = 3.141592` as an estimate for Pi. (Hint: you may need to
+   use `let pi = 3.141592` as an estimate for pi. (Hint: you may need to
    check the [`std::fmt`][fmt] documentation for setting the number of
    decimals to display)
 

src/hello/print/fmt.md

@@ -26,7 +26,7 @@ struct City {
 }
 
 impl Display for City {
-    // `f` is a buffer, this method must write the formatted string into it
+    // `f` is a buffer, and this method must write the formatted string into it
     fn fmt(&self, f: &mut Formatter) -> fmt::Result {
         let lat_c = if self.lat >= 0.0 { 'N' } else { 'S' };
         let lon_c = if self.lon >= 0.0 { 'E' } else { 'W' };
@@ -59,7 +59,7 @@ fn main() {
         Color { red: 0, green: 0, blue: 0 },
     ].iter() {
         // Switch this to use {} once you've added an implementation
-        // for fmt::Display
+        // for fmt::Display.
         println!("{:?}", *color);
     }
 }

src/hello/print/print_debug.md

@@ -11,7 +11,7 @@ not true for `fmt::Display` which must be manually implemented.
 
 ```rust
 // This structure cannot be printed either with `fmt::Display` or
-// with `fmt::Debug`
+// with `fmt::Debug`.
 struct UnPrintable(i32);
 
 // The `derive` attribute automatically creates the implementation

src/hello/print/print_display.md

@@ -9,11 +9,11 @@ looks like this:
 // Import (via `use`) the `fmt` module to make it available.
 use std::fmt;
 
-// Define a structure which `fmt::Display` will be implemented for. This is simply
-// a tuple struct containing an `i32` bound to the name `Structure`.
+// Define a structure for which `fmt::Display` will be implemented. This is
+// a tuple struct named `Structure` that contains an `i32`.
 struct Structure(i32);
 
-// In order to use the `{}` marker, the trait `fmt::Display` must be implemented
+// To use the `{}` marker, the trait `fmt::Display` must be implemented
 // manually for the type.
 impl fmt::Display for Structure {
     // This trait requires `fmt` with this exact signature.
@@ -30,7 +30,7 @@ impl fmt::Display for Structure {
 `fmt::Display` may be cleaner than `fmt::Debug` but this presents
 a problem for the `std` library. How should ambiguous types be displayed?
 For example, if the `std` library implemented a single style for all
-`Vec<T>`, what style should it be? Either of these two?
+`Vec<T>`, what style should it be? Would it be either of these two?
 
 * `Vec<path>`: `/:/etc:/home/username:/bin` (split on `:`)
 * `Vec<number>`: `1,2,3` (split on `,`)
@@ -66,7 +66,7 @@ struct Point2D {
     y: f64,
 }
 
-// Similarly, implement for Point2D
+// Similarly, implement `Display` for `Point2D`
 impl fmt::Display for Point2D {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         // Customize so only `x` and `y` are denoted.
@@ -94,7 +94,7 @@ fn main() {
     println!("Display: {}", point);
     println!("Debug: {:?}", point);
 
-    // Error. Both `Debug` and `Display` were implemented but `{:b}`
+    // Error. Both `Debug` and `Display` were implemented, but `{:b}`
     // requires `fmt::Binary` to be implemented. This will not work.
     // println!("What does Point2D look like in binary: {:b}?", point);
 }
@@ -107,7 +107,7 @@ each requires its own implementation. This is detailed further in
 
 ### Activity
 
-After checking the output of the above example, use the `Point2D` struct as
+After checking the output of the above example, use the `Point2D` struct as a
 guide to add a Complex struct to the example. When printed in the same
 way, the output should be:
 

src/hello/print/print_display/testcase_list.md

@@ -32,7 +32,7 @@ struct List(Vec<i32>);
 
 impl fmt::Display for List {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        // Extract the value using tuple indexing
+        // Extract the value using tuple indexing,
         // and create a reference to `vec`.
         let vec = &self.0;
 
@@ -47,7 +47,7 @@ impl fmt::Display for List {
             write!(f, "{}", v)?;
         }
 
-        // Close the opened bracket and return a fmt::Result value
+        // Close the opened bracket and return a fmt::Result value.
         write!(f, "]")
     }
 }