Added a bunch of extra documentation

[flimdejong]

Comments for the reviewer

Pre pull request checklist:

Code Quality

• Is the code is understandable and easy to read
• Changes to the code comply with set clang-format rules
• No use of manual memory control (e.g new/malloc/colloc etc)
• Are (only) smart pointers used?

Testing

• All tests are passing.
• I added new / changed existing tests to reflect code changes (state why not otherwise!)
• I tested my changes manually (Describe how, to what extent etc.)

Commit Messages

• Commit message is saying what has been changed, why it was changed? Remember other developers might not know
  what the problem you are fixing was. Note also negative decision (e.g., why did you not do particular thing)
  TLDR: Commit message are comprehensive
• Commit messages follows the rules of https://chris.beams.io/posts/git-commit/