book: add sections about threading

[elenaf9]

Extracted from #133.

Add sections about multi-threading / riot-rs-threads to user and developer guide in the book.

Couple of open questions (marked as TODOs) within the text.

Happy to add additional sections/ details if you think anything is missing, or to remove stuff that might be too deep or still subject to change.

[elenaf9]

Friendly ping @kaspar030, mind giving a review here? :)
Everyone else is also welcome to leave comments/ suggestions.

[kaspar030]

As asked elsewhere: this would be useful as an example. maybe just copy examples/threading to examples/threading_channel, put his code there, then use here via mdbook include (with anchor)?

(We can postpone that to a follow up)

[elenaf9]

Implemented in #223.

[kaspar030]

Please add a line here describing the scheduling policy (highest runnable thread always running).

[elenaf9]

Done in 402434e.

[ROMemories]

It looks to me that most of this could become rustdoc of the riot-rs-threads crate. Keeping the docs closer to the impl would make them more likely to get updated when the implementation changes, and allow to link to items, again preventing the docs from lagging behind in case items are removed/renamed (broken internal links are already tested in CI).
If the concern is for some of the doc to not become SemVer'd implementation guarantees, I think they could be moved to a docs submodule in riot-rs-threads, explicitly excluded from SemVer guarantees in the text, and only rendered in the dev version of the rustdoc using the (upcoming) _devdoc feature (by feature-gating the docs module).

[elenaf9]

It looks to me that most of this could become rustdoc of the riot-rs-threads crate. Keeping the docs closer to the impl would make them more likely to get updated when the implementation changes, and allow to link to items, again preventing the docs from lagging behind in case items are removed/renamed (broken internal links are already tested in CI).

I agree. Most of these docs are extracted from the rustdocs anyway, but they could be moved into library/ module level docs in riot-rs-threads. However, if I understood @emmanuelsearch and @kaspar030 correctly, their idea was to additionally have these separate user- and developer guides in the book.

[elenaf9]

Closing this PR.
We agreed in an out-of-band discussion that these kind of docs should be rustdocs inside the crate, instead of book sections.
I've extracted the user-guide docs in #449.
The developer-guide docs were in fact simply a summary of our existing docs/ code-comments, so nothing new really.