Merge pull request #1535 from robertefry/comment_cleanup

docs: cleanup the explanation paragraphs at the start of each exercise.

Author: manyinsects

exercises/clippy/clippy1.rs

@@ -1,10 +1,13 @@
 // clippy1.rs
-// The Clippy tool is a collection of lints to analyze your code
-// so you can catch common mistakes and improve your Rust code.
 //
-// For these exercises the code will fail to compile when there are clippy warnings
-// check clippy's suggestions from the output to solve the exercise.
-// Execute `rustlings hint clippy1` or use the `hint` watch subcommand for a hint.
+// The Clippy tool is a collection of lints to analyze your code so you can
+// catch common mistakes and improve your Rust code.
+//
+// For these exercises the code will fail to compile when there are clippy
+// warnings check clippy's suggestions from the output to solve the exercise.
+//
+// Execute `rustlings hint clippy1` or use the `hint` watch subcommand for a
+// hint.
 
 // I AM NOT DONE
 

exercises/clippy/clippy2.rs

@@ -1,5 +1,7 @@
 // clippy2.rs
-// Execute `rustlings hint clippy2` or use the `hint` watch subcommand for a hint.
+// 
+// Execute `rustlings hint clippy2` or use the `hint` watch subcommand for a
+// hint.
 
 // I AM NOT DONE
 

exercises/clippy/clippy3.rs

@@ -1,5 +1,8 @@
 // clippy3.rs
+// 
 // Here's a couple more easy Clippy fixes, so you can see its utility.
+//
+// Execute `rustlings hint clippy3` or use the `hint` watch subcommand for a hint.
 
 // I AM NOT DONE
 

exercises/conversions/as_ref_mut.rs

@@ -1,7 +1,11 @@
-// AsRef and AsMut allow for cheap reference-to-reference conversions.
-// Read more about them at https://doc.rust-lang.org/std/convert/trait.AsRef.html
-// and https://doc.rust-lang.org/std/convert/trait.AsMut.html, respectively.
-// Execute `rustlings hint as_ref_mut` or use the `hint` watch subcommand for a hint.
+// as_ref_mut.rs
+//
+// AsRef and AsMut allow for cheap reference-to-reference conversions. Read more
+// about them at https://doc.rust-lang.org/std/convert/trait.AsRef.html and
+// https://doc.rust-lang.org/std/convert/trait.AsMut.html, respectively.
+//
+// Execute `rustlings hint as_ref_mut` or use the `hint` watch subcommand for a
+// hint.
 
 // I AM NOT DONE
 

exercises/conversions/from_into.rs

@@ -1,7 +1,11 @@
-// The From trait is used for value-to-value conversions.
-// If From is implemented correctly for a type, the Into trait should work conversely.
-// You can read more about it at https://doc.rust-lang.org/std/convert/trait.From.html
-// Execute `rustlings hint from_into` or use the `hint` watch subcommand for a hint.
+// from_into.rs
+//
+// The From trait is used for value-to-value conversions. If From is implemented
+// correctly for a type, the Into trait should work conversely. You can read
+// more about it at https://doc.rust-lang.org/std/convert/trait.From.html
+//
+// Execute `rustlings hint from_into` or use the `hint` watch subcommand for a
+// hint.
 
 #[derive(Debug)]
 struct Person {
@@ -20,20 +24,21 @@ impl Default for Person {
     }
 }
 
-// Your task is to complete this implementation
-// in order for the line `let p = Person::from("Mark,20")` to compile
-// Please note that you'll need to parse the age component into a `usize`
-// with something like `"4".parse::<usize>()`. The outcome of this needs to
-// be handled appropriately.
+// Your task is to complete this implementation in order for the line `let p =
+// Person::from("Mark,20")` to compile Please note that you'll need to parse the
+// age component into a `usize` with something like `"4".parse::<usize>()`. The
+// outcome of this needs to be handled appropriately.
 //
 // Steps:
-// 1. If the length of the provided string is 0, then return the default of Person
-// 2. Split the given string on the commas present in it
-// 3. Extract the first element from the split operation and use it as the name
-// 4. If the name is empty, then return the default of Person
-// 5. Extract the other element from the split operation and parse it into a `usize` as the age
-// If while parsing the age, something goes wrong, then return the default of Person
-// Otherwise, then return an instantiated Person object with the results
+// 1. If the length of the provided string is 0, then return the default of
+//    Person.
+// 2. Split the given string on the commas present in it.
+// 3. Extract the first element from the split operation and use it as the name.
+// 4. If the name is empty, then return the default of Person.
+// 5. Extract the other element from the split operation and parse it into a
+//    `usize` as the age.
+// If while parsing the age, something goes wrong, then return the default of
+// Person Otherwise, then return an instantiated Person object with the results
 
 // I AM NOT DONE
 
@@ -77,7 +82,8 @@ mod tests {
     }
     #[test]
     fn test_bad_age() {
-        // Test that "Mark,twenty" will return the default person due to an error in parsing age
+        // Test that "Mark,twenty" will return the default person due to an
+        // error in parsing age
         let p = Person::from("Mark,twenty");
         assert_eq!(p.name, "John");
         assert_eq!(p.age, 30);

exercises/conversions/from_str.rs

@@ -1,10 +1,13 @@
 // from_str.rs
-// This is similar to from_into.rs, but this time we'll implement `FromStr`
-// and return errors instead of falling back to a default value.
-// Additionally, upon implementing FromStr, you can use the `parse` method
-// on strings to generate an object of the implementor type.
-// You can read more about it at https://doc.rust-lang.org/std/str/trait.FromStr.html
-// Execute `rustlings hint from_str` or use the `hint` watch subcommand for a hint.
+//
+// This is similar to from_into.rs, but this time we'll implement `FromStr` and
+// return errors instead of falling back to a default value. Additionally, upon
+// implementing FromStr, you can use the `parse` method on strings to generate
+// an object of the implementor type. You can read more about it at
+// https://doc.rust-lang.org/std/str/trait.FromStr.html
+//
+// Execute `rustlings hint from_str` or use the `hint` watch subcommand for a
+// hint.
 
 use std::num::ParseIntError;
 use std::str::FromStr;
@@ -33,15 +36,18 @@ enum ParsePersonError {
 // Steps:
 // 1. If the length of the provided string is 0, an error should be returned
 // 2. Split the given string on the commas present in it
-// 3. Only 2 elements should be returned from the split, otherwise return an error
+// 3. Only 2 elements should be returned from the split, otherwise return an
+//    error
 // 4. Extract the first element from the split operation and use it as the name
-// 5. Extract the other element from the split operation and parse it into a `usize` as the age
-//    with something like `"4".parse::<usize>()`
-// 6. If while extracting the name and the age something goes wrong, an error should be returned
+// 5. Extract the other element from the split operation and parse it into a
+//    `usize` as the age with something like `"4".parse::<usize>()`
+// 6. If while extracting the name and the age something goes wrong, an error
+//    should be returned
 // If everything goes well, then return a Result of a Person object
 //
-// As an aside: `Box<dyn Error>` implements `From<&'_ str>`. This means that if you want to return a
-// string error message, you can do so via just using return `Err("my error message".into())`.
+// As an aside: `Box<dyn Error>` implements `From<&'_ str>`. This means that if
+// you want to return a string error message, you can do so via just using
+// return `Err("my error message".into())`.
 
 impl FromStr for Person {
     type Err = ParsePersonError;

exercises/conversions/try_from_into.rs

@@ -1,9 +1,13 @@
 // try_from_into.rs
-// TryFrom is a simple and safe type conversion that may fail in a controlled way under some circumstances.
-// Basically, this is the same as From. The main difference is that this should return a Result type
-// instead of the target type itself.
-// You can read more about it at https://doc.rust-lang.org/std/convert/trait.TryFrom.html
-// Execute `rustlings hint try_from_into` or use the `hint` watch subcommand for a hint.
+//
+// TryFrom is a simple and safe type conversion that may fail in a controlled
+// way under some circumstances. Basically, this is the same as From. The main
+// difference is that this should return a Result type instead of the target
+// type itself. You can read more about it at
+// https://doc.rust-lang.org/std/convert/trait.TryFrom.html
+//
+// Execute `rustlings hint try_from_into` or use the `hint` watch subcommand for
+// a hint.
 
 use std::convert::{TryFrom, TryInto};
 
@@ -25,14 +29,13 @@ enum IntoColorError {
 
 // I AM NOT DONE
 
-// Your task is to complete this implementation
-// and return an Ok result of inner type Color.
-// You need to create an implementation for a tuple of three integers,
-// an array of three integers, and a slice of integers.
+// Your task is to complete this implementation and return an Ok result of inner
+// type Color. You need to create an implementation for a tuple of three
+// integers, an array of three integers, and a slice of integers.
 //
-// Note that the implementation for tuple and array will be checked at compile time,
-// but the slice implementation needs to check the slice length!
-// Also note that correct RGB color values must be integers in the 0..=255 range.
+// Note that the implementation for tuple and array will be checked at compile
+// time, but the slice implementation needs to check the slice length! Also note
+// that correct RGB color values must be integers in the 0..=255 range.
 
 // Tuple implementation
 impl TryFrom<(i16, i16, i16)> for Color {

exercises/conversions/using_as.rs

@@ -1,10 +1,14 @@
-// Type casting in Rust is done via the usage of the `as` operator.
-// Please note that the `as` operator is not only used when type casting.
-// It also helps with renaming imports.
+// using_as.rs
 //
-// The goal is to make sure that the division does not fail to compile
-// and returns the proper type.
-// Execute `rustlings hint using_as` or use the `hint` watch subcommand for a hint.
+// Type casting in Rust is done via the usage of the `as` operator. Please note
+// that the `as` operator is not only used when type casting. It also helps with
+// renaming imports.
+//
+// The goal is to make sure that the division does not fail to compile and
+// returns the proper type.
+//
+// Execute `rustlings hint using_as` or use the `hint` watch subcommand for a
+// hint.
 
 // I AM NOT DONE
 

exercises/enums/enums1.rs

@@ -1,4 +1,5 @@
 // enums1.rs
+//
 // No hints this time! ;)
 
 // I AM NOT DONE

exercises/enums/enums2.rs

@@ -1,5 +1,7 @@
 // enums2.rs
-// Execute `rustlings hint enums2` or use the `hint` watch subcommand for a hint.
+//
+// Execute `rustlings hint enums2` or use the `hint` watch subcommand for a
+// hint.
 
 // I AM NOT DONE