As described in #165 , Gateway induced changes of entity structs do not
get propagated to other structs holding the "same" object which got
updated. This is bad because it means that structs still hold
potentially outdated info.
My proposed solution is to create components and composites. A component
is an object with information which is supposed to be the same in at
least 2 structs, such as a Channel object ("channels" field in Guild
struct and lone Channel object for example). These components should be
shared instead of cloned, to make sure that an update to this shared
structs fields is reflected everywhere the struct is being used.
We can do this by using `Arc<Mutex<T>>`. Mutex can be the
std::sync::Mutex, as long as locks on the components themselves are not
being held across .await points. ~~This draft is not yet finished, but~~
all instances of components in composite entity structs have been
replaced with their `Arc<Mutex<T>>` counterparts already.
This pr is focused on improving doc comments, along with some minor
changes
Changes (up to now):
- Make all doc comments use `///`
- Fix links (links that aren't actually links, links such as
`[https://discord.com](https://discord.com)` -> `<https://discord.com>`)
- Remove unnecessary docs that only restate what the function signature
already says
- Document some previously undocumented types
- Change `Result<_, crate::errors::ChorusError>` to `ChorusResult<_>`
- Rename `create_guild_invite` to `create_channel_invite` (See the
surrounding code and the endpoint used)
Should close#129