Merge pull request #723 from Zerotask/update-exercises-readme

manyinsects · web-flow · commit 2b2fbe918e28 · 2021-04-24T11:45:37.000+02:00
docs(exercises): consistent excersises README.md files
diff --git a/exercises/clippy/README.md b/exercises/clippy/README.md
@@ -1,8 +1,10 @@
-### Clippy
+# Clippy
 
 The Clippy tool is a collection of lints to analyze your code so you can catch common mistakes and improve your Rust code.
 
 If you used the installation script for Rustlings, Clippy should be already installed.
 If not you can install it manually via `rustup component add clippy`.
 
-For more information about Clippy lints, please see [their documentation page](https://rust-lang.github.io/rust-clippy/master/).
+## Further information
+
+- [GitHub Repository](https://github.com/rust-lang/rust-clippy).
diff --git a/exercises/collections/README.md b/exercises/collections/README.md
@@ -1,4 +1,4 @@
-### Collections
+# Collections
 
 Rust’s standard library includes a number of very useful data
 structures called collections. Most other data types represent one
@@ -17,4 +17,6 @@ structures that are used very often in Rust programs:
   You may also know this by the names [*unordered map* in C++](https://en.cppreference.com/w/cpp/container/unordered_map), 
   [*dictionary* in Python](https://docs.python.org/3/tutorial/datastructures.html#dictionaries) or an *associative array* in other languages.
 
-[Rust book chapter](https://doc.rust-lang.org/stable/book/ch08-01-vectors.html)
+## Further information
+
+- [Storing Lists of Values with Vectors](https://doc.rust-lang.org/stable/book/ch08-01-vectors.html)
diff --git a/exercises/conversions/README.md b/exercises/conversions/README.md
@@ -1,5 +1,4 @@
-### Type conversions
-
+# Type conversions
 
 Rust offers a multitude of ways to convert a value of a given type into another type.
 
@@ -15,6 +14,8 @@ Furthermore, the `std::str` module offers a trait called [`FromStr`](https://doc
 
 These should be the main ways ***within the standard library*** to convert data into your desired types.
 
-#### Book Sections
+## Further information
 
-These are not directly covered in the book, but the standard library has great documentation for [conversions here](https://doc.rust-lang.org/std/convert/index.html). The `FromStr` trait is also covered [here](https://doc.rust-lang.org/std/str/trait.FromStr.html).
+These are not directly covered in the book, but the standard library has a great documentation for it.
+- [conversions](https://doc.rust-lang.org/std/convert/index.html)
+- [`FromStr` trait](https://doc.rust-lang.org/std/str/trait.FromStr.html)
diff --git a/exercises/enums/README.md b/exercises/enums/README.md
@@ -1,10 +1,10 @@
-### Enums
+# Enums
 
 Rust allows you to define types called "enums" which enumerate possible values.
 Enums are a feature in many languages, but their capabilities differ in each language. Rust’s enums are most similar to algebraic data types in functional languages, such as F#, OCaml, and Haskell.
 Useful in combination with enums is Rust's "pattern matching" facility, which makes it easy to run different code for different values of an enumeration.
 
-#### Book Sections
+## Further information
 
 - [Enums](https://doc.rust-lang.org/book/ch06-00-enums.html)
 - [Pattern syntax](https://doc.rust-lang.org/book/ch18-03-pattern-syntax.html)
diff --git a/exercises/error_handling/README.md b/exercises/error_handling/README.md
@@ -1,11 +1,11 @@
-For this exercise check out the sections:
-- [Error Handling](https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html)
-- [Generics](https://doc.rust-lang.org/book/ch10-01-syntax.html)
+# Error handling
+Most errors aren’t serious enough to require the program to stop entirely. 
+Sometimes, when a function fails, it’s for a reason that you can easily interpret and respond to.
+For example, if you try to open a file and that operation fails because the file doesn’t exist, you might want to create the file instead of terminating the process.
 
-of the Rust Book.
+## Further information
 
-or alternatively, check out the sections:
+- [Error Handling](https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html)
+- [Generics](https://doc.rust-lang.org/book/ch10-01-syntax.html)
 - [Result](https://doc.rust-lang.org/rust-by-example/error/result.html)
 - [Boxing errors](https://doc.rust-lang.org/rust-by-example/error/multiple_error_types/boxing_errors.html)
-  
-of the Rust By Example Book.
diff --git a/exercises/functions/README.md b/exercises/functions/README.md
@@ -1,7 +1,7 @@
-### Functions
+# Functions
 
 Here, you'll learn how to write functions and how Rust's compiler can trace things way back.
 
-#### Book Sections
+## Further information
 
 - [How Functions Work](https://doc.rust-lang.org/book/ch03-03-how-functions-work.html)
diff --git a/exercises/generics/README.md b/exercises/generics/README.md
@@ -1,8 +1,11 @@
-### Generics
+# Generics
 
-In this section you'll learn about saving yourself many lines of code with generics!
+Generics is the topic of generalizing types and functionalities to broader cases.
+This is extremely useful for reducing code duplication in many ways, but can call for rather involving syntax.
+Namely, being generic requires taking great care to specify over which types a generic type is actually considered valid.
+The simplest and most common use of generics is for type parameters.
 
-### Book Sections
+## Further information
 
 - [Generic Data Types](https://doc.rust-lang.org/stable/book/ch10-01-syntax.html)
 - [Bounds](https://doc.rust-lang.org/rust-by-example/generics/bounds.html)
diff --git a/exercises/if/README.md b/exercises/if/README.md
@@ -1,7 +1,7 @@
-### If
+# If
 
 `if`, the most basic type of control flow, is what you'll learn here.
 
-#### Book Sections
+## Further information
 
 - [Control Flow - if expressions](https://doc.rust-lang.org/book/ch03-05-control-flow.html#if-expressions)
diff --git a/exercises/macros/README.md b/exercises/macros/README.md
@@ -1,10 +1,10 @@
-### Macros
+# Macros
 
 Rust's macro system is very powerful, but also kind of difficult to wrap your
 head around. We're not going to teach you how to write your own fully-featured
 macros. Instead, we'll show you how to use and create them.
 
-#### Book Sections
+## Further information
 
 - [Macros](https://doc.rust-lang.org/book/ch19-06-macros.html)
 - [The Little Book of Rust Macros](https://danielkeep.github.io/tlborm/book/index.html)
diff --git a/exercises/modules/README.md b/exercises/modules/README.md
@@ -1,7 +1,7 @@
-### Modules
+# Modules
 
 In this section we'll give you an introduction to Rust's module system.
 
-#### Book Sections
+## Further information
 
 - [The Module System](https://doc.rust-lang.org/book/ch07-02-defining-modules-to-control-scope-and-privacy.html)
diff --git a/exercises/move_semantics/README.md b/exercises/move_semantics/README.md
@@ -1,8 +1,8 @@
-### Move Semantics
+# Move Semantics
 
 These exercises are adapted from [pnkfelix](https://github.com/pnkfelix)'s [Rust Tutorial](https://pnkfelix.github.io/rust-examples-icfp2014/) -- Thank you Felix!!!
 
-#### Book Sections
+## Further information
 
 For this section, the book links are especially important.
 
diff --git a/exercises/option/README.md b/exercises/option/README.md
@@ -1,8 +1,17 @@
-### Option
+# Option
 
-#### Book Sections
+Type Option represents an optional value: every Option is either Some and contains a value, or None, and does not. 
+Option types are very common in Rust code, as they have a number of uses:
+- Initial values
+- Return values for functions that are not defined over their entire input range (partial functions)
+- Return value for otherwise reporting simple errors, where None is returned on error
+- Optional struct fields
+- Struct fields that can be loaned or "taken"
+- Optional function arguments
+- Nullable pointers
+- Swapping things out of difficult situations
 
-To learn about Option<T>, check out these links:
+## Further Information
 
 - [Option Enum Format](https://doc.rust-lang.org/stable/book/ch10-01-syntax.html#in-enum-definitions)
 - [Option Module Documentation](https://doc.rust-lang.org/std/option/)
diff --git a/exercises/primitive_types/README.md b/exercises/primitive_types/README.md
@@ -1,9 +1,9 @@
-### Primitive Types
+# Primitive Types
 
 Rust has a couple of basic types that are directly implemented into the
 compiler. In this section, we'll go through the most important ones.
 
-#### Book Sections
+## Further information
 
 - [Data Types](https://doc.rust-lang.org/stable/book/ch03-02-data-types.html)
 - [The Slice Type](https://doc.rust-lang.org/stable/book/ch04-03-slices.html)
diff --git a/exercises/standard_library_types/README.md b/exercises/standard_library_types/README.md
@@ -1,5 +1,10 @@
-For the Box exercise check out the chapter [Using Box to Point to Data on the Heap](https://doc.rust-lang.org/book/ch15-01-box.html).
+# Standard library types
 
-For the Arc exercise check out the chapter [Shared-State Concurrency](https://doc.rust-lang.org/book/ch16-03-shared-state.html) of the Rust Book.
+This section will teach you about Box, Shared-State Concurrency and Iterators.
 
-For the Iterator exercise check out the chapters [Iterator](https://doc.rust-lang.org/book/ch13-02-iterators.html) of the Rust Book and the [Iterator documentation](https://doc.rust-lang.org/stable/std/iter/).
+## Further information
+
+- [Using Box to Point to Data on the Heap](https://doc.rust-lang.org/book/ch15-01-box.html)
+- [Shared-State Concurrency](https://doc.rust-lang.org/book/ch16-03-shared-state.html)
+- [Iterator](https://doc.rust-lang.org/book/ch13-02-iterators.html)
+- [Iterator documentation](https://doc.rust-lang.org/stable/std/iter/)
diff --git a/exercises/strings/README.md b/exercises/strings/README.md
@@ -1,9 +1,9 @@
-### Strings
+# Strings
 
 Rust has two string types, a string slice (`&str`) and an owned string (`String`).
 We're not going to dictate when you should use which one, but we'll show you how
 to identify and create them, as well as use them.
 
-#### Book Sections
+## Further information
 
 - [Strings](https://doc.rust-lang.org/book/ch08-02-strings.html)
diff --git a/exercises/structs/README.md b/exercises/structs/README.md
@@ -1,8 +1,8 @@
-### Structs
+# Structs
 
 Rust has three struct types: a classic C struct, a tuple struct, and a unit struct.
 
-#### Book Sections
+## Further information
 
 - [Structures](https://doc.rust-lang.org/book/ch05-01-defining-structs.html)
 - [Method Syntax](https://doc.rust-lang.org/book/ch05-03-method-syntax.html)
diff --git a/exercises/tests/README.md b/exercises/tests/README.md
@@ -1,7 +1,7 @@
-### Tests
+# Tests
 
 Going out of order from the book to cover tests -- many of the following exercises will ask you to make tests pass!
 
-#### Book Sections
+## Further information
 
 - [Writing Tests](https://doc.rust-lang.org/book/ch11-01-writing-tests.html)
diff --git a/exercises/threads/README.md b/exercises/threads/README.md
@@ -1 +1,9 @@
-For this exercise check out the [Dining Philosophers example](https://doc.rust-lang.org/1.4.0/book/dining-philosophers.html) and the chapter [Concurrency](https://doc.rust-lang.org/book/ch16-01-threads.html) of the Rust Book.
+# Threads
+
+In most current operating systems, an executed program’s code is run in a process, and the operating system manages multiple processes at once.
+Within your program, you can also have independent parts that run simultaneously. The features that run these independent parts are called threads.
+
+## Further information
+
+- [Dining Philosophers example](https://doc.rust-lang.org/1.4.0/book/dining-philosophers.html)
+- [Using Threads to Run Code Simultaneously](https://doc.rust-lang.org/book/ch16-01-threads.html)
diff --git a/exercises/traits/README.md b/exercises/traits/README.md
@@ -1,4 +1,4 @@
-### Traits
+# Traits
 
 A trait is a collection of methods.
 
@@ -7,14 +7,13 @@ Data types can implement traits. To do so, the methods making up the trait are d
 In this way, traits are somewhat similar to Java interfaces and C++ abstract classes.
 
 Some additional common Rust traits include:
-
-+ `Clone` (the `clone` method),
-+ `Display` (which allows formatted display via `{}`), and
-+ `Debug` (which allows formatted display via `{:?}`).
+- `Clone` (the `clone` method)
+- `Display` (which allows formatted display via `{}`)
+- `Debug` (which allows formatted display via `{:?}`)
 
 Because traits indicate shared behavior between data types, they are useful when writing generics.
 
 
-#### Book Sections
+## Further information
 
 - [Traits](https://doc.rust-lang.org/book/ch10-02-traits.html)
diff --git a/exercises/variables/README.md b/exercises/variables/README.md
@@ -1,7 +1,9 @@
-### Variables
+# Variables
 
-Here you'll learn about simple variables.
+In Rust, variables are immutable by default.
+When a variable is immutable, once a value is bound to a name, you can’t change that value.
+You can make them mutable by adding mut in front of the variable name.
 
-#### Book Sections
+## Further information
 
 - [Variables and Mutability](https://doc.rust-lang.org/book/ch03-01-variables-and-mutability.html)
