refactor(threads): improve panic handling and docs

[elenaf9]

Description

Add some missing documentation about possible panics in riot-rs-threads when a function is expected to be called only inside a thread context.
Avoid panics where possible through early returns.

Also adds some documentation for Channel.

Issues/PRs references

Extracted from #381 (comment).

Open Questions

• @ROMemories you proposed in feat(threads): sort ThreadList by priority #381 (comment) to use NOTE(no-panic)-style comments to document why an unwrap can't panic. I've instead used expect, because we a) don't know that it will never panic (it's the callers responsibility) and b) it prints the comment as part of the panic message. Wdyt?

• Avoid panics where possible through early returns.

This concerns the functions yield_same and sleep. If called from outside a thread context, the operations are now no-ops, instead of causing panics. Do you agree that we should prefer no-ops over panics as long as it doesn't cause any undefined behavior?

Change checklist

• I have cleaned up my commit history and squashed fixup commits.
• I have followed the Coding Conventions.
• I have performed a self-review of my own code.
• I have made corresponding changes to the documentation.

[ROMemories]

That leaves the documentation of this module in a much better state.
I'm not sure about the expects vs unwraps however ; given these don't depend on runtime data at all, only on the proper usage of the methods, maybe it would make sense to add debug_assert!s with a developer-friendly message, and unwrap otherwise (or maybe even use unreachable_unchecked if that's any useful performance-wise). @kaspar030 wdyt?

[elenaf9]

maybe it would make sense to add debug_assert!s with a developer-friendly message, and unwrap otherwise

What would be the advantage of this compared to using expect?

According to the Rust docs about Converting Errors into Panics:

Of the two, expect is generally preferred since its msg field allows you to convey your intent and assumptions which makes tracking down the source of a panic easier.

[ROMemories]

What would be the advantage of this compared to using expect?

I'm somewhat concerned about the binary size, as these expect() strings end up in the binary. Not saying that the unwrap()s are necessarily smaller (this should ideally be measured), but using unwrap in these cases makes it rather clear that we don't actually care about providing a user-friendly error message in these cases, which could allow us to later optimize these (almost impossible in production) panics for (binary) size.

[kaspar030]

lgtm!