docs(exercises): consistent exercise description

a description starts with the filename, has an optional description and
ends with help information

exercises/clippy/clippy1.rs

@@ -1,10 +1,12 @@
 // 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` for hints :)
+//
+// If you need help, open the corresponding README.md or run: rustlings hint clippy1
 
 // I AM NOT DONE
 

exercises/clippy/clippy2.rs

@@ -1,5 +1,8 @@
 // clippy2.rs
-// Make me compile! Execute `rustlings hint clippy2` for hints :)
+//
+// Make me compile! 
+//
+// If you need help, open the corresponding README.md or run: rustlings hint clippy2
 
 // I AM NOT DONE
 

exercises/collections/hashmap1.rs

@@ -1,4 +1,5 @@
 // hashmap1.rs
+//
 // A basket of fruits in the form of a hash map needs to be defined.
 // The key represents the name of the fruit and the value represents
 // how many of that particular fruit is in the basket. You have to put
@@ -8,8 +9,7 @@
 //
 // Make me compile and pass the tests!
 //
-// Execute the command `rustlings hint hashmap1` if you need
-// hints.
+// If you need help, open the corresponding README.md or run: rustlings hint hashmap1
 
 // I AM NOT DONE
 

exercises/collections/hashmap2.rs

@@ -1,5 +1,5 @@
 // hashmap2.rs
-
+//
 // A basket of fruits in the form of a hash map is given. The key
 // represents the name of the fruit and the value represents how many
 // of that particular fruit is in the basket. You have to put *MORE
@@ -9,8 +9,7 @@
 //
 // Make me pass the tests!
 //
-// Execute the command `rustlings hint hashmap2` if you need
-// hints.
+// If you need help, open the corresponding README.md or run: rustlings hint hashmap2
 
 // I AM NOT DONE
 

exercises/collections/vec1.rs

@@ -1,8 +1,10 @@
 // vec1.rs
+//
 // Your task is to create a `Vec` which holds the exact same elements
 // as in the array `a`.
 // Make me compile and pass the test!
-// Execute the command `rustlings hint vec1` if you need hints.
+//
+// If you need help, open the corresponding README.md or run: rustlings hint vec1
 
 // I AM NOT DONE
 

exercises/collections/vec2.rs

@@ -1,11 +1,11 @@
 // vec2.rs
+//
 // A Vec of even numbers is given. Your task is to complete the loop
 // so that each number in the Vec is multiplied by 2.
 //
 // Make me pass the test!
 //
-// Execute the command `rustlings hint vec2` if you need
-// hints.
+// If you need help, open the corresponding README.md or run: rustlings hint vec2
 
 // I AM NOT DONE
 

exercises/conversions/as_ref_mut.rs

@@ -1,6 +1,10 @@
+// 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.
+//
+// If you need help, open the corresponding README.md or run: rustlings hint as_ref_mut
 
 // I AM NOT DONE
 

exercises/conversions/from_into.rs

@@ -1,6 +1,27 @@
+// 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
+// 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
+//
+// If you need help, open the corresponding README.md or run: rustlings hint from_into
+
+// I AM NOT DONE
+
 #[derive(Debug)]
 struct Person {
     name: String,
@@ -18,26 +39,8 @@ 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.
-//
-// 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
-
-// I AM NOT DONE
-
 impl From<&str> for Person {
-    fn from(s: &str) -> Person {
-    }
+    fn from(s: &str) -> Person {}
 }
 
 fn main() {

exercises/conversions/from_str.rs

@@ -1,7 +1,25 @@
+// from_str.rs
+//
 // This does practically the same thing that TryFrom<&str> does.
 // 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
+//
+// 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
+// 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>()`
+//
+// 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
+//
+// If you need help, open the corresponding README.md or run: rustlings hint from_str
+
+// I AM NOT DONE
+
 use std::error;
 use std::str::FromStr;
 
@@ -11,18 +29,6 @@ struct Person {
     age: usize,
 }
 
-// I AM NOT DONE
-
-// 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
-// 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>()`
-// 5. 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
-
 impl FromStr for Person {
     type Err = Box<dyn error::Error>;
     fn from_str(s: &str) -> Result<Person, Self::Err> {

exercises/conversions/try_from_into.rs

@@ -1,7 +1,23 @@
+// 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
+//
+// 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.
+//
+// If you need help, open the corresponding README.md or run: rustlings hint try_from_into
+
+// I AM NOT DONE
+
 use std::convert::{TryFrom, TryInto};
 use std::error;
 
@@ -12,17 +28,6 @@ struct Color {
     blue: u8,
 }
 
-// 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.
-//
-// 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 {
     type Error = Box<dyn error::Error>;

exercises/conversions/using_as.rs

@@ -1,9 +1,13 @@
+// using_as.rs
+//
 // 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.
+//
+// If you need help, open the corresponding README.md or run: rustlings hint using_as
 
 // I AM NOT DONE
 

exercises/enums/enums1.rs

@@ -1,5 +1,8 @@
 // enums1.rs
-// Make me compile! Execute `rustlings hint enums1` for hints!
+//
+// Make me compile! 
+//
+// If you need help, open the corresponding README.md or run: rustlings hint enums1
 
 // I AM NOT DONE
 

exercises/enums/enums2.rs

@@ -1,5 +1,8 @@
 // enums2.rs
-// Make me compile! Execute `rustlings hint enums2` for hints!
+//
+// Make me compile!
+//
+// If you need help, open the corresponding README.md or run: rustlings hint enums2
 
 // I AM NOT DONE
 

exercises/enums/enums3.rs

@@ -1,5 +1,8 @@
 // enums3.rs
+//
 // Address all the TODOs to make the tests pass!
+//
+// If you need help, open the corresponding README.md or run: rustlings hint enums3
 
 // I AM NOT DONE
 

exercises/error_handling/errors1.rs

@@ -1,10 +1,12 @@
 // errors1.rs
+//
 // This function refuses to generate text to be printed on a nametag if
 // you pass it an empty string. It'd be nicer if it explained what the problem
 // was, instead of just sometimes returning `None`. The 2nd test currently
 // does not compile or pass, but it illustrates the behavior we would like
 // this function to have.
-// Execute `rustlings hint errors1` for hints!
+//
+// If you need help, open the corresponding README.md or run: rustlings hint errors1
 
 // I AM NOT DONE
 

exercises/error_handling/errors2.rs

@@ -1,20 +1,23 @@
 // errors2.rs
+//
 // Say we're writing a game where you can buy items with tokens. All items cost
 // 5 tokens, and whenever you purchase items there is a processing fee of 1
 // token. A player of the game will type in how many items they want to buy,
 // and the `total_cost` function will calculate the total number of tokens.
 // Since the player typed in the quantity, though, we get it as a string-- and
 // they might have typed anything, not just numbers!
-
+//
 // Right now, this function isn't handling the error case at all (and isn't
 // handling the success case properly either). What we want to do is:
 // if we call the `parse` function on a string that is not a number, that
 // function will return a `ParseIntError`, and in that case, we want to
 // immediately return that error from our function and not try to multiply
 // and add.
-
+//
 // There are at least two ways to implement this that are both correct-- but
 // one is a lot shorter! Execute `rustlings hint errors2` for hints to both ways.
+//
+// If you need help, open the corresponding README.md or run: rustlings hint errors2
 
 // I AM NOT DONE
 

exercises/error_handling/errors3.rs

@@ -1,8 +1,10 @@
 // errors3.rs
+//
 // This is a program that is trying to use a completed version of the
 // `total_cost` function from the previous exercise. It's not working though!
 // Why not? What should we do to fix it?
-// Execute `rustlings hint errors3` for hints!
+//
+// If you need help, open the corresponding README.md or run: rustlings hint errors3
 
 // I AM NOT DONE
 

exercises/error_handling/errorsn.rs

@@ -1,4 +1,5 @@
 // errorsn.rs
+//
 // This is a bigger error exercise than the previous ones!
 // You can do it! :)
 //
@@ -15,7 +16,7 @@
 // type goes where the question marks are, and how do we return
 // that type from the body of read_and_validate?
 //
-// Execute `rustlings hint errorsn` for hints :)
+// If you need help, open the corresponding README.md or run: rustlings hint errorsn
 
 // I AM NOT DONE
 

exercises/error_handling/result1.rs

@@ -1,5 +1,8 @@
 // result1.rs
-// Make this test pass! Execute `rustlings hint result1` for hints :)
+//
+// Make this test pass!
+//
+// If you need help, open the corresponding README.md or run: rustlings hint result1
 
 // I AM NOT DONE
 

exercises/functions/functions1.rs

@@ -1,5 +1,8 @@
 // functions1.rs
-// Make me compile! Execute `rustlings hint functions1` for hints :)
+//
+// Make me compile!
+//
+// If you need help, open the corresponding README.md or run: rustlings hint functions1
 
 // I AM NOT DONE
 

exercises/functions/functions2.rs

@@ -1,5 +1,8 @@
 // functions2.rs
-// Make me compile! Execute `rustlings hint functions2` for hints :)
+//
+// Make me compile!
+//
+// If you need help, open the corresponding README.md or run: rustlings hint functions2
 
 // I AM NOT DONE
 

exercises/functions/functions3.rs

@@ -1,5 +1,8 @@
 // functions3.rs
-// Make me compile! Execute `rustlings hint functions3` for hints :)
+//
+// Make me compile!
+//
+// If you need help, open the corresponding README.md or run: rustlings hint functions3
 
 // I AM NOT DONE
 

exercises/functions/functions4.rs

@@ -1,8 +1,10 @@
 // functions4.rs
-// Make me compile! Execute `rustlings hint functions4` for hints :)
-
+//
 // This store is having a sale where if the price is an even number, you get
 // 10 Rustbucks off, but if it's an odd number, it's 3 Rustbucks off.
+// Make me compile!
+//
+// If you need help, open the corresponding README.md or run: rustlings hint functions4
 
 // I AM NOT DONE
 

exercises/functions/functions5.rs

@@ -1,5 +1,8 @@
 // functions5.rs
-// Make me compile! Execute `rustlings hint functions5` for hints :)
+//
+// Make me compile!
+//
+// If you need help, open the corresponding README.md or run: rustlings hint functions5
 
 // I AM NOT DONE
 

exercises/generics/generics1.rs

@@ -1,5 +1,9 @@
+// generics1.rs
+//
 // This shopping list program isn't compiling!
 // Use your knowledge of generics to fix it.
+//
+// If you need help, open the corresponding README.md or run: rustlings hint generics1
 
 // I AM NOT DONE
 

exercises/generics/generics2.rs

@@ -1,5 +1,9 @@
+// generics2.rs
+//
 // This powerful wrapper provides the ability to store a positive integer value.
 // Rewrite it using generics so that it supports wrapping ANY type.
+//
+// If you need help, open the corresponding README.md or run: rustlings hint generics2
 
 // I AM NOT DONE
 

exercises/generics/generics3.rs

@@ -1,14 +1,16 @@
+// generics3.rs
+//
 // An imaginary magical school has a new report card generation system written in Rust!
 // Currently the system only supports creating report cards where the student's grade
 // is represented numerically (e.g. 1.0 -> 5.5).
 // However, the school also issues alphabetical grades (A+ -> F-) and needs
 // to be able to print both types of report card!
-
+//
 // Make the necessary code changes in the struct ReportCard and the impl block
 // to support alphabetical report cards. Change the Grade in the second test to "A+"
 // to show that your changes allow alphabetical grades.
-
-// Execute 'rustlings hint generics3' for hints!
+//
+// If you need help, open the corresponding README.md or run: rustlings hint generics3
 
 // I AM NOT DONE
 
@@ -20,8 +22,10 @@ pub struct ReportCard {
 
 impl ReportCard {
     pub fn print(&self) -> String {
-        format!("{} ({}) - achieved a grade of {}",
-            &self.student_name, &self.student_age, &self.grade)
+        format!(
+            "{} ({}) - achieved a grade of {}",
+            &self.student_name, &self.student_age, &self.grade
+        )
     }
 }