Document everything

[ZoopOTheGoop]

This documents just about everything possible, to make future work easier. It's best to proofread this locally using cargo doc --no-deps --open and read through it on the webpage.

My understanding of how this was structured grew as a wrote it so I'd appreciate any corrections of anything I said erroneously I didn't understand and forgot to go back and correct.

I also have some notes for future development not relevant to this PR, but fit here because I noticed them while working. Feel free to disagree (probably probably on Matrix). I'll work on refactoring them later if they seem good:

notes:
Don't store Snap ID every time in Ratings

Clean up modules (in particular put trait impls in the same module as the struct they're doing an impl on)

Borrow more instead of cloning

A lot of free functions should probably be added to the thing they create. The stuff in use_case is also confusing
in how it just delegates to interface

Similarly things like ratings_band is more idiomatically an impl on VoteSummary called [to_ratings_band] or somesuch

A lot of things can be coverted to impls on structs from the protobuf object (e.g. build_service can be impld on the protobuf object from another module instead of a free function, and is more idiomatic that way)

No reason to separate use_cases and infrastructure unless I'm missing something

In library code, good to derive more not less. At minimal most things should derive Clone, Copy (if possible), Debug, PartialEq, Eq,
and Serialize/Deserialize. Unused derives will be compiled out.

Imports I normalized to

std::{whatever}

external crate 1::{...}
external crate 2::{...}
...
external crate n::{...}

crate::{...}

Likewise modules I normalized to

pub use ...

pub mod 1.
pub mod 2.
pub mod 3

mod 1
mod 2
mod 3

A lot of the failable new functions should probably be try_new but probably not a big deal

A lot of things (e.g. URIs) should probably be bespoke types (e.g. std::https::uri) or use their types defined elsewhere (e.g. ClientHash) instead of just Strings. More idiomatic, less error prone, more self-documenting

[matthew-hagemann]

Hi Zoe 🙂 thank you for this!
So allot of seemingly strange layout and structure choices come from us using a blend of a few architecture patterns.

I started writing a review with notes on why we made certain decisions, but I think the fastest and best approach will be hopping on a call sometime this week and do a walk-through review / handover.

[matthew-hagemann]

I don't feel "Definitions" is completely accurate, as this also has behavior implementation for how the config will be loaded. Goes back to these being secondary adapters wrapping external utilities.

[matthew-hagemann]

Awesome! Thank you Zoe! 2 small changes and 1 comment, but otherwise merge when ready 🙂