From 382e16eb7ea66cddc4860f4b19453b031a2a8a8a Mon Sep 17 00:00:00 2001 From: Ali Afsharzadeh Date: Thu, 30 Mar 2023 19:53:22 +0330 Subject: [PATCH] feat(docs): add markdown linter for exercises README.md files --- .github/workflows/lint.yml | 18 ++++++++++++++++++ .markdownlint.yml | 2 ++ exercises/conversions/README.md | 4 +++- exercises/hashmaps/README.md | 3 ++- exercises/lifetimes/README.md | 12 ++++++------ exercises/macros/README.md | 2 +- exercises/options/README.md | 3 ++- exercises/smart_pointers/README.md | 1 + exercises/traits/README.md | 2 +- 9 files changed, 36 insertions(+), 11 deletions(-) create mode 100644 .github/workflows/lint.yml create mode 100644 .markdownlint.yml diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 00000000..67339d1b --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,18 @@ +name: Lint + +on: + push: + branches: + - main + pull_request: + branches: + - main + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: DavidAnson/markdownlint-cli2-action@v9 + with: + globs: "exercises/**/*.md" diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 00000000..d5f7e391 --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,2 @@ +# MD013/line-length Line length, Expected: 80 +MD013: false diff --git a/exercises/conversions/README.md b/exercises/conversions/README.md index 8d7da93e..619a78c5 100644 --- a/exercises/conversions/README.md +++ b/exercises/conversions/README.md @@ -6,6 +6,7 @@ The simplest form of type conversion is a type cast expression. It is denoted wi Rust also offers traits that facilitate type conversions upon implementation. These traits can be found under the [`convert`](https://doc.rust-lang.org/std/convert/index.html) module. The traits are the following: + - `From` and `Into` covered in [`from_into`](from_into.rs) - `TryFrom` and `TryInto` covered in [`try_from_into`](try_from_into.rs) - `AsRef` and `AsMut` covered in [`as_ref_mut`](as_ref_mut.rs) @@ -17,5 +18,6 @@ These should be the main ways ***within the standard library*** to convert data ## Further information 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 +- [`FromStr` trait](https://doc.rust-lang.org/std/str/trait.FromStr.html) diff --git a/exercises/hashmaps/README.md b/exercises/hashmaps/README.md index 30471cf9..80ec1441 100644 --- a/exercises/hashmaps/README.md +++ b/exercises/hashmaps/README.md @@ -1,6 +1,7 @@ # Hashmaps + A *hash map* allows you to associate a value with a particular key. -You may also know this by the names [*unordered map* in C++](https://en.cppreference.com/w/cpp/container/unordered_map), +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. This is the other data structure that we've been talking about before, when diff --git a/exercises/lifetimes/README.md b/exercises/lifetimes/README.md index 74a4a786..91373f73 100644 --- a/exercises/lifetimes/README.md +++ b/exercises/lifetimes/README.md @@ -3,17 +3,17 @@ Lifetimes tell the compiler how to check whether references live long enough to be valid in any given situation. For example lifetimes say "make sure parameter 'a' lives as long as parameter 'b' so that the return -value is valid". +value is valid". -They are only necessary on borrows, i.e. references, +They are only necessary on borrows, i.e. references, since copied parameters or moves are owned in their scope and cannot be referenced outside. Lifetimes mean that calling code of e.g. functions -can be checked to make sure their arguments are valid. Lifetimes are +can be checked to make sure their arguments are valid. Lifetimes are restrictive of their callers. -If you'd like to learn more about lifetime annotations, the -[lifetimekata](https://tfpk.github.io/lifetimekata/) project -has a similar style of exercises to Rustlings, but is all about +If you'd like to learn more about lifetime annotations, the +[lifetimekata](https://tfpk.github.io/lifetimekata/) project +has a similar style of exercises to Rustlings, but is all about learning to write lifetime annotations. ## Further information diff --git a/exercises/macros/README.md b/exercises/macros/README.md index e34bc3a8..337816d6 100644 --- a/exercises/macros/README.md +++ b/exercises/macros/README.md @@ -4,7 +4,7 @@ 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. -If you'd like to learn more about writing your own macros, the +If you'd like to learn more about writing your own macros, the [macrokata](https://github.com/tfpk/macrokata) project has a similar style of exercises to Rustlings, but is all about learning to write Macros. diff --git a/exercises/options/README.md b/exercises/options/README.md index 6140a167..bdd33749 100644 --- a/exercises/options/README.md +++ b/exercises/options/README.md @@ -1,7 +1,8 @@ # Options -Type Option represents an optional value: every Option is either Some and contains a value, or None, and does not. +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 diff --git a/exercises/smart_pointers/README.md b/exercises/smart_pointers/README.md index c517ae31..d56d2b62 100644 --- a/exercises/smart_pointers/README.md +++ b/exercises/smart_pointers/README.md @@ -1,4 +1,5 @@ # Smart Pointers + In Rust, smart pointers are variables that contain an address in memory and reference some other data, but they also have additional metadata and capabilities. Smart pointers in Rust often own the data they point to, while references only borrow data. diff --git a/exercises/traits/README.md b/exercises/traits/README.md index de67acd0..ac87c64e 100644 --- a/exercises/traits/README.md +++ b/exercises/traits/README.md @@ -7,13 +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 `{}`) - `Debug` (which allows formatted display via `{:?}`) Because traits indicate shared behavior between data types, they are useful when writing generics. - ## Further information - [Traits](https://doc.rust-lang.org/book/ch10-02-traits.html)