Added more reference docs

[onel]

This is a first round of adding minimal reference docs.
Working on a more comprehensive addition right now.

Issue: #337

[jonashaag]

@onel thanks for taking a stab at this! Good comments should focus on the "why", not the "what" or the "how". The latter are already described by the code, and if you duplicate that information as comments, it gets out of sync with the implementation really quickly.

[onel]

@onel thanks for taking a stab at this! Good comments should focus on the "why", not the "what" or the "how". The latter are already described by the code, and if you duplicate that information as comments, it gets out of sync with the implementation really quickly.

Those are good points. Going through your comments and will update the PR soon