Merge #385

385: Doclints r=korken89 a=dcarosone

Some minor doc lints and wording cleanup

Co-authored-by: Daniel Carosone <Daniel.Carosone@gmail.com>

book/en/src/by-example/resources.md

@@ -1,4 +1,4 @@
-## Resources
+# Resources
 
 The framework provides an abstraction to share data between any of the contexts
 we saw in the previous section (task handlers, `init` and `idle`): resources.
@@ -116,7 +116,9 @@ are required to access the resource even if the resource is contended by several
 tasks running at different priorities. The downside is that the task only gets a
 shared reference (`&-`) to the resource, limiting the operations it can perform
 on it, but where a shared reference is enough this approach reduces the number
-of required locks.
+of required locks. In addition to simple immutable data, this shared access can
+be useful where the resource type safely implements interior mutability, with
+appropriate locking or atomic operations of its own.
 
 Note that in this release of RTIC it is not possible to request both exclusive
 access (`&mut-`) and shared access (`&-`) to the *same* resource from different

book/en/src/by-example/tips.md

@@ -116,6 +116,7 @@ Here's an example where `heapless::Pool` is used to "box" buffers of 128 bytes.
 ``` rust
 {{#include ../../../../examples/pool.rs}}
 ```
+
 ``` console
 $ cargo run --example pool
 {{#include ../../../../ci/expected/pool.run}}

book/en/src/migration/migration_rtic.md

@@ -8,14 +8,11 @@ change.
 
 [RFC #33]: https://github.com/rtic-rs/rfcs/pull/33
 
-
-
 ## `Cargo.toml`
 
 First, the `cortex-m-rtfm` dependency needs to be updated to
 `cortex-m-rtic`.
 
-
 ``` toml
 [dependencies]
 # change this
@@ -51,4 +48,3 @@ const APP: () = {
 
 };
 ```
-

book/en/src/migration/migration_v4.md

@@ -3,7 +3,7 @@
 This section covers how to upgrade an application written against RTIC v0.4.x to
 the version v0.5.0 of the framework.
 
-### `Cargo.toml`
+## `Cargo.toml`
 
 First, the version of the `cortex-m-rtic` dependency needs to be updated to
 `"0.5.0"`. The `timer-queue` feature needs to be removed.
@@ -21,7 +21,7 @@ features = ["timer-queue"]
 #           ^^^^^^^^^^^^^
 ```
 
-### `Context` argument
+## `Context` argument
 
 All functions inside the `#[rtic::app]` item need to take as first argument a
 `Context` structure. This `Context` type will contain the variables that were
@@ -73,7 +73,7 @@ const APP: () = {
 };
 ```
 
-### Resources
+## Resources
 
 The syntax used to declare resources has been changed from `static mut`
 variables to a `struct Resources`.
@@ -97,7 +97,7 @@ const APP: () = {
 };
 ```
 
-### Device peripherals
+## Device peripherals
 
 If your application was accessing the device peripherals in `#[init]` through
 the `device` variable then you'll need to add `peripherals = true` to the
@@ -135,7 +135,7 @@ const APP: () = {
 };
 ```
 
-### `#[interrupt]` and `#[exception]`
+## `#[interrupt]` and `#[exception]`
 
 The `#[interrupt]` and `#[exception]` attributes have been removed. To declare
 hardware tasks in v0.5.x use the `#[task]` attribute with the `binds` argument.
@@ -181,9 +181,10 @@ const APP: () = {
 };
 ```
 
-### `schedule`
+## `schedule`
 
-The `timer-queue` feature has been removed. To use the `schedule` API one must
+The `schedule` API no longer requires the `timer-queue` cargo feature, which has
+been removed. To use the `schedule` API one must
 first define the monotonic timer the runtime will use using the `monotonic`
 argument of the `#[rtic::app]` attribute. To continue using the cycle counter
 (CYCCNT) as the monotonic timer, and match the behavior of version v0.4.x, add

book/en/src/migration/migration_v5.md

@@ -2,11 +2,11 @@
 
 This section describes how to upgrade from v0.5.x to v0.6.0 of the RTIC framework.
 
-### `Cargo.toml` - version bump
+## `Cargo.toml` - version bump
 
 Change the version of `cortex-m-rtic` to `"0.6.0"`.
 
-### Module instead of Const
+## Module instead of Const
 
 With the support of attributes on modules the `const APP` workaround is not needed.
 
@@ -32,7 +32,7 @@ Now that a regular Rust module is used it means it is possible to have custom
 user code within that module.
 Additionally, it means that `use`-statements for resources etc may be required.
 
-### Init always returns late resources
+## Init always returns late resources
 
 In order to make the API more symmetric the #[init]-task always returns a late resource.
 
@@ -64,7 +64,7 @@ mod app {
 }
 ```
 
-### Resources struct - #[resources]
+## Resources struct - #[resources]
 
 Previously the RTIC resources had to be in in a struct named exactly "Resources":