Skip to content

Commit

Permalink
Improve docs
Browse files Browse the repository at this point in the history
- Fix typos

- Follow markdown linter to improve style:
  * Remove redundant empty lines
  * Insert empty lines for readability
  * remove trailing spaces
  • Loading branch information
ShapelessCat committed Sep 29, 2024
1 parent 00be0f9 commit 0e22153
Show file tree
Hide file tree
Showing 91 changed files with 240 additions and 205 deletions.
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ abide by the [Rust code of conduct], which you can find at that link or in the

## License

RBE is dual licenced under the MIT and Apache 2.0 licenses, and so are all
RBE is dual licensed under the MIT and Apache 2.0 licenses, and so are all
contributions. Please see the [`LICENSE-MIT`] and [`LICENSE-APACHE`] files in
this directory for more details.

Expand Down Expand Up @@ -55,7 +55,7 @@ $ mdbook build

**The following warnings can be ignored safely.**

```
```text
[WARN] (mdbook::preprocess::cmd): The command wasn't found, is the "gettext" preprocessor installed?
[WARN] (mdbook::preprocess::cmd): Command: mdbook-gettext
```
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ read all content offline, however!

**The following warnings can be ignored safely.**

```
```text
[WARN] (mdbook::preprocess::cmd): The command wasn't found, is the "gettext" preprocessor installed?
[WARN] (mdbook::preprocess::cmd): Command: mdbook-gettext
```
Expand Down
2 changes: 1 addition & 1 deletion TRANSLATING.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot"}}' \
msginit -i po/messages.pot -l xx -o po/xx.po
```

#### Updating the exising translation resource
#### Updating the existing translation resource

```bash
msgmerge --update po/xx.po po/messages.pot
Expand Down
6 changes: 4 additions & 2 deletions src/attribute.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,12 @@ can be used to/for:
Attributes look like `#[outer_attribute]` or `#![inner_attribute]`,
with the difference between them being where they apply.

- `#[outer_attribute]` applies to the [item][item] immediately
* `#[outer_attribute]` applies to the [item][item] immediately
following it. Some examples of items are: a function, a module
declaration, a constant, a structure, an enum. Here is an example
where attribute `#[derive(Debug)]` applies to the struct
`Rectangle`:

```rust
#[derive(Debug)]
struct Rectangle {
Expand All @@ -30,11 +31,12 @@ with the difference between them being where they apply.
}
```

- `#![inner_attribute]` applies to the enclosing [item][item] (typically a
* `#![inner_attribute]` applies to the enclosing [item][item] (typically a
module or a crate). In other words, this attribute is interpreted as
applying to the entire scope in which it's placed. Here is an example
where `#![allow(unused_variables)]` applies to the whole crate (if
placed in `main.rs`):

```rust
#![allow(unused_variables)]

Expand Down
1 change: 0 additions & 1 deletion src/cargo/deps.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,5 @@ rebuilds what it has not already built, similar to `make`).

Voila! That's all there is to it!


[manifest]: https://doc.rust-lang.org/cargo/reference/manifest.html
[dependencies]: https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html
14 changes: 8 additions & 6 deletions src/cargo/test.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,7 @@

As we know testing is integral to any piece of software! Rust has first-class
support for unit and integration testing ([see this
chapter](https://doc.rust-lang.org/book/ch11-00-testing.html) in
TRPL).
chapter](https://doc.rust-lang.org/book/ch11-00-testing.html) in TRPL).

From the testing chapters linked above, we see how to write unit tests and
integration tests. Organizationally, we can place unit tests in the modules they
Expand All @@ -20,13 +19,13 @@ foo
└── my_other_test.rs
```

Each file in `tests` is a separate
Each file in `tests` is a separate
[integration test](https://doc.rust-lang.org/book/ch11-03-test-organization.html#integration-tests),
i.e. a test that is meant to test your library as if it were being called from a dependent
crate.

The [Testing][testing] chapter elaborates on the three different testing styles:
[Unit][unit_testing], [Doc][doc_testing], and [Integration][integration_testing].
The [Testing][testing] chapter elaborates on the three different testing styles:
[Unit][unit_testing], [Doc][doc_testing], and [Integration][integration_testing].

`cargo` naturally provides an easy way to run all of your tests!

Expand Down Expand Up @@ -71,7 +70,7 @@ test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 2 filtered out
```

One word of caution: Cargo may run multiple tests concurrently, so make sure
that they don't race with each other.
that they don't race with each other.

One example of this concurrency causing issues is if two tests output to a
file, such as below:
Expand Down Expand Up @@ -120,6 +119,7 @@ mod tests {
```

Although the intent is to get the following:

```shell
$ cat ferris.txt
Ferris
Expand All @@ -133,7 +133,9 @@ Corro
Corro
Corro
```

What actually gets put into `ferris.txt` is this:

```shell
$ cargo test test_file && cat ferris.txt
Corro
Expand Down
2 changes: 1 addition & 1 deletion src/compatibility.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Compatibility

The Rust language is fastly evolving, and because of this certain compatibility
The Rust language is evolving rapidly, and because of this certain compatibility
issues can arise, despite efforts to ensure forwards-compatibility wherever
possible.

Expand Down
4 changes: 2 additions & 2 deletions src/conversion/from_into.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,8 +73,8 @@ fn main() {

`From` and `Into` are designed to be complementary.
We do not need to provide an implementation for both traits.
If you have implemented the `From` trait for your type, `Into` will call it
when necessary. Note, however, that the converse is not true: implementing `Into` for your type will not automatically provide it with an implementation of `From`.
If you have implemented the `From` trait for your type, `Into` will call it
when necessary. Note, however, that the converse is not true: implementing `Into` for your type will not automatically provide it with an implementation of `From`.

```rust,editable
use std::convert::From;
Expand Down
2 changes: 1 addition & 1 deletion src/conversion/string.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

To convert any type to a `String` is as simple as implementing the [`ToString`]
trait for the type. Rather than doing so directly, you should implement the
[`fmt::Display`][Display] trait which automagically provides [`ToString`] and
[`fmt::Display`][Display] trait which automatically provides [`ToString`] and
also allows printing the type as discussed in the section on [`print!`][print].

```rust,editable
Expand Down
2 changes: 1 addition & 1 deletion src/crates/lib.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,4 +31,4 @@ crate file, but this default name can be overridden by passing
the `--crate-name` option to `rustc` or by using the [`crate_name`
attribute][crate-name].

[crate-name]: ../attribute/crate.md
[crate-name]: ../attribute/crate.md
2 changes: 1 addition & 1 deletion src/crates/using_lib.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Using a Library

To link a crate to this new library you may use `rustc`'s `--extern` flag. All
To link a crate to this new library you may use `rustc`'s `--extern` flag. All
of its items will then be imported under a module named the same as the library.
This module generally behaves the same way as any other module.

Expand Down
2 changes: 1 addition & 1 deletion src/custom_types.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@ Rust custom data types are formed mainly through the two keywords:
* `struct`: define a structure
* `enum`: define an enumeration

Constants can also be created via the `const` and `static` keywords.
Constants can also be created via the `const` and `static` keywords.
2 changes: 1 addition & 1 deletion src/custom_types/enum/enum_use.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ fn main() {

### See also:

[`match`][match] and [`use`][use]
[`match`][match] and [`use`][use]

[use]: ../../mod/use.md
[match]: ../../flow_control/match.md
4 changes: 1 addition & 3 deletions src/error/abort_unwind.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
# `abort` and `unwind`

The previous section illustrates the error handling mechanism `panic`. Different code paths can be conditionally compiled based on the panic setting. The current values available are `unwind` and `abort`.

The previous section illustrates the error handling mechanism `panic`. Different code paths can be conditionally compiled based on the panic setting. The current values available are `unwind` and `abort`.

Building on the prior lemonade example, we explicitly use the panic strategy to exercise different lines of code.

Expand Down Expand Up @@ -57,4 +56,3 @@ The panic strategy can be set from the command line by using `abort` or `unwind`
```console
rustc lemonade.rs -C panic=abort
```

8 changes: 4 additions & 4 deletions src/error/multiple_error_types/define_error_type.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@ Rust allows us to define our own error types. In general, a "good" error type:
* Represents different errors with the same type
* Presents nice error messages to the user
* Is easy to compare with other types
- Good: `Err(EmptyVec)`
- Bad: `Err("Please use a vector with at least one element".to_owned())`
* Good: `Err(EmptyVec)`
* Bad: `Err("Please use a vector with at least one element".to_owned())`
* Can hold information about the error
- Good: `Err(BadChar(c, position))`
- Bad: `Err("+ cannot be used here".to_owned())`
* Good: `Err(BadChar(c, position))`
* Bad: `Err("+ cannot be used here".to_owned())`
* Composes well with other errors

```rust,editable
Expand Down
1 change: 0 additions & 1 deletion src/error/multiple_error_types/wrap_error.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,6 @@ for you.

[`From::from`][from] and [`Enums`][enums]


[`Crates for handling errors`][crates-errors]

[from]: https://doc.rust-lang.org/std/convert/trait.From.html
Expand Down
2 changes: 1 addition & 1 deletion src/error/option_unwrap.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ We told our program to `panic` if we drink a sugary lemonade.
But what if we expect _some_ drink but don't receive one?
That case would be just as bad, so it needs to be handled!

We *could* test this against the null string (`""`) as we do with a lemonade.
We _could_ test this against the null string (`""`) as we do with a lemonade.
Since we're using Rust, let's instead have the compiler point out cases
where there's no drink.

Expand Down
10 changes: 5 additions & 5 deletions src/error/option_unwrap/and_then.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Combinators: `and_then`

`map()` was described as a chainable way to simplify `match` statements.
However, using `map()` on a function that returns an `Option<T>` results
in the nested `Option<Option<T>>`. Chaining multiple calls together can
then become confusing. That's where another combinator called `and_then()`,
`map()` was described as a chainable way to simplify `match` statements.
However, using `map()` on a function that returns an `Option<T>` results
in the nested `Option<Option<T>>`. Chaining multiple calls together can
then become confusing. That's where another combinator called `and_then()`,
known in some languages as flatmap, comes in.

`and_then()` calls its function input with the wrapped value and returns the result. If the `Option` is `None`, then it returns `None` instead.

In the following example, `cookable_v3()` results in an `Option<Food>`.
In the following example, `cookable_v3()` results in an `Option<Food>`.
Using `map()` instead of `and_then()` would have given an
`Option<Option<Food>>`, which is an invalid type for `eat()`.

Expand Down
10 changes: 6 additions & 4 deletions src/error/option_unwrap/defaults.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
# Unpacking options and defaults

There is more than one way to unpack an `Option` and fall back on a default if it is `None`. To choose the one that meets our needs, we need to consider the following:

* do we need eager or lazy evaluation?
* do we need to keep the original empty value intact, or modify it in place?

## `or()` is chainable, evaluates eagerly, keeps empty value intact
## `or()` is chainable, evaluates eagerly, keeps empty value intact

`or()`is chainable and eagerly evaluates its argument, as is shown in the following example. Note that because `or`'s arguments are evaluated eagerly, the variable passed to `or` is moved.

Expand All @@ -29,7 +30,7 @@ fn main() {
}
```

## `or_else()` is chainable, evaluates lazily, keeps empty value intact
## `or_else()` is chainable, evaluates lazily, keeps empty value intact

Another alternative is to use `or_else`, which is also chainable, and evaluates lazily, as is shown in the following example:

Expand Down Expand Up @@ -57,7 +58,7 @@ fn main() {
}
```

## `get_or_insert()` evaluates eagerly, modifies empty value in place
## `get_or_insert()` evaluates eagerly, modifies empty value in place

To make sure that an `Option` contains a value, we can use `get_or_insert` to modify it in place with a fallback value, as is shown in the following example. Note that `get_or_insert` eagerly evaluates its parameter, so variable `apple` is moved:

Expand All @@ -78,9 +79,10 @@ fn main() {
}
```

## `get_or_insert_with()` evaluates lazily, modifies empty value in place
## `get_or_insert_with()` evaluates lazily, modifies empty value in place

Instead of explicitly providing a value to fall back on, we can pass a closure to `get_or_insert_with`, as follows:

```rust,editable
#[derive(Debug)]
enum Fruit { Apple, Orange, Banana, Kiwi, Lemon }
Expand Down
10 changes: 5 additions & 5 deletions src/error/option_unwrap/map.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# Combinators: `map`

`match` is a valid method for handling `Option`s. However, you may
eventually find heavy usage tedious, especially with operations only valid
with an input. In these cases, [combinators][combinators] can be used to
`match` is a valid method for handling `Option`s. However, you may
eventually find heavy usage tedious, especially with operations only valid
with an input. In these cases, [combinators][combinators] can be used to
manage control flow in a modular fashion.

`Option` has a built in method called `map()`, a combinator for the simple
mapping of `Some -> Some` and `None -> None`. Multiple `map()` calls can be
`Option` has a built in method called `map()`, a combinator for the simple
mapping of `Some -> Some` and `None -> None`. Multiple `map()` calls can be
chained together for even more flexibility.

In the following example, `process()` replaces all functions previous
Expand Down
4 changes: 2 additions & 2 deletions src/error/option_unwrap/question_mark.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ function is being executed and return `None`.

```rust,editable
fn next_birthday(current_age: Option<u8>) -> Option<String> {
// If `current_age` is `None`, this returns `None`.
// If `current_age` is `Some`, the inner `u8` value + 1
// If `current_age` is `None`, this returns `None`.
// If `current_age` is `Some`, the inner `u8` value + 1
// gets assigned to `next_age`
let next_age: u8 = current_age? + 1;
Some(format!("Next year I will be {}", next_age))
Expand Down
1 change: 0 additions & 1 deletion src/error/result.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,6 @@ fn main() -> Result<(), ParseIntError> {
}
```


[option]: https://doc.rust-lang.org/std/option/enum.Option.html
[result]: https://doc.rust-lang.org/std/result/enum.Result.html
[parse]: https://doc.rust-lang.org/std/primitive.str.html#method.parse
Expand Down
1 change: 0 additions & 1 deletion src/error/result/enter_question_mark.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,6 @@ fn main() {
}
```


[^]: See [re-enter ?][re_enter_?] for more details.

[re_enter_?]: ../multiple_error_types/reenter_question_mark.md
5 changes: 1 addition & 4 deletions src/flow_control/let_else.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,10 @@
# let-else


> 🛈 stable since: rust 1.65
>
> 🛈 you can target specific edition by compiling like this
> `rustc --edition=2021 main.rs`

With `let`-`else`, a refutable pattern can match and bind variables
in the surrounding scope like a normal `let`, or else diverge (e.g. `break`,
`return`, `panic!`) when the pattern doesn't match.
Expand Down Expand Up @@ -58,8 +56,7 @@ patterns with an unfortunate bit of repetition and an outer `let`:

[option][option], [match][match], [if let][if_let] and the [let-else RFC][let_else_rfc].


[match]: ./match.md
[if_let]: ./if_let.md
[let_else_rfc]: https://rust-lang.github.io/rfcs/3137-let-else.html
[option]: ../std/option.md
[option]: ../std/option.md
2 changes: 1 addition & 1 deletion src/flow_control/loop.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,4 @@ fn main() {
}
}
}
```
```
1 change: 1 addition & 0 deletions src/flow_control/match/binding.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ fn main() {
```

### See also:

[`functions`][functions], [`enums`][enums] and [`Option`][option]

[functions]: ../../fn.md
Expand Down
1 change: 0 additions & 1 deletion src/flow_control/match/destructuring.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ A `match` block can destructure items in a variety of ways.
* [Destructuring Pointers][refs]
* [Destructuring Structures][struct]


[enum]: destructuring/destructure_enum.md
[refs]: destructuring/destructure_pointers.md
[struct]: destructuring/destructure_structures.md
Expand Down
4 changes: 2 additions & 2 deletions src/flow_control/match/destructuring/destructure_pointers.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ For pointers, a distinction needs to be made between destructuring
and dereferencing as they are different concepts which are used
differently from languages like C/C++.

* Dereferencing uses `*`
* Destructuring uses `&`, `ref`, and `ref mut`
* Dereferencing uses `*`
* Destructuring uses `&`, `ref`, and `ref mut`

```rust,editable
fn main() {
Expand Down
Loading

0 comments on commit 0e22153

Please sign in to comment.