From 249ad44cc03974fd34708c23d9832b1729c6e844 Mon Sep 17 00:00:00 2001 From: Zerotask Date: Fri, 23 Apr 2021 19:54:31 +0200 Subject: [PATCH] docs(exercises): updated all exercises readme files all exercises readme files now have a unified structure and a description --- exercises/clippy/README.md | 6 ++++-- exercises/collections/README.md | 6 ++++-- exercises/conversions/README.md | 9 +++++---- exercises/enums/README.md | 4 ++-- exercises/error_handling/README.md | 14 +++++++------- exercises/functions/README.md | 4 ++-- exercises/generics/README.md | 9 ++++++--- exercises/if/README.md | 4 ++-- exercises/macros/README.md | 4 ++-- exercises/modules/README.md | 4 ++-- exercises/move_semantics/README.md | 4 ++-- exercises/option/README.md | 15 ++++++++++++--- exercises/primitive_types/README.md | 4 ++-- exercises/standard_library_types/README.md | 11 ++++++++--- exercises/strings/README.md | 4 ++-- exercises/structs/README.md | 4 ++-- exercises/tests/README.md | 4 ++-- exercises/threads/README.md | 10 +++++++++- exercises/traits/README.md | 11 +++++------ exercises/variables/README.md | 8 +++++--- 20 files changed, 85 insertions(+), 54 deletions(-) diff --git a/exercises/clippy/README.md b/exercises/clippy/README.md index 60a12fe..55438af 100644 --- 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 index af87863..0291bc8 100644 --- 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 index 114bd42..8d7da93 100644 --- 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). \ No newline at end of file +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) \ No newline at end of file diff --git a/exercises/enums/README.md b/exercises/enums/README.md index 091f5d0..30d4d91 100644 --- 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 index 478510a..5255ace 100644 --- 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 +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. + +## Further information + - [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) - -of the Rust Book. - -or alternatively, check out the sections: - [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 index 351ae02..66547bd 100644 --- 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 index 12170d4..de46d50 100644 --- 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 index b115721..528d988 100644 --- 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 index b48b880..319d840 100644 --- 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 index bb76510..6582b00 100644 --- 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 index 6842af7..54ddd8e 100644 --- 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 index d17b79c..a304bb4 100644 --- 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, 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 index daa70ee..cea69b0 100644 --- 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 index 8b53dd8..809d61f 100644 --- 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 index 38d24c8..fa2104c 100644 --- 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 index 58e5a6a..3fc1fdc 100644 --- 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 index dbb14a8..27c6818 100644 --- 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 index 2024292..d086694 100644 --- 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. \ No newline at end of file +# 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 index 8cd03ec..de67acd 100644 --- 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 index 1e2eb59..11a7a78 100644 --- 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)