docs: Improve code documentation

[orpheuslummis]

Relevant issue(s)

Resolves #496 #154

Description

Improves in-repo documentation and the feel of the rendered code documentation.

It is meant to be a collaborative draft PR, in which we can all feel free to push commits improving the documentation onto the branch.

Tasks

• I made sure the code is well commented, particularly hard-to-understand areas.
• I made sure the repository-held documentation is changed accordingly.
• I made sure the pull request title adheres to the conventional commit style (the subset used in the project can be found in tools/configs/chglog/config.yml).
• I made sure to discuss its limitations such as threats to validity, vulnerability to mistake and misuse, robustness to invalidation of assumptions, resource requirements, ...

How has this been tested?

This should only touch (code) documentation.

[codecov]

Codecov Report

Merging #533 (02ef2d7) into develop (10f5fb0) will decrease coverage by 0.00%.
The diff coverage is 80.00%.

@@             Coverage Diff             @@
##           develop     #533      +/-   ##
===========================================
- Coverage    56.59%   56.58%   -0.01%     
===========================================
  Files          121      121              
  Lines        14083    14082       -1     
===========================================
- Hits          7970     7969       -1     
  Misses        5421     5421              
  Partials       692      692              

Impacted Files	Coverage Δ
api/http/router.go	100.00% <ø> (ø)
api/http/server.go	100.00% <ø> (ø)
client/dockey.go	51.16% <ø> (ø)
core/crdt/composite.go	76.05% <ø> (ø)
core/crdt/lwwreg.go	74.39% <ø> (ø)
core/data.go	88.73% <ø> (ø)
core/doc.go	93.61% <ø> (ø)
core/key.go	85.97% <ø> (ø)
datastore/blockstore.go	45.05% <ø> (ø)
datastore/dag.go	100.00% <ø> (ø)
... and 27 more

[fredcarle]

Good first effort on this Orphée!

[orpheuslummis]

closes #154
adding this comment to include the issue because it didn't worked as part of the PR text
update: this doesn't work either so the issue will be closed after the fact

[AndrewSisley]

LGTM! Cheers for taking the time to do this. One suggestion I would offer for the future however is to group changes under different commits - would make reviewing a bit easier (e.g. lets=>let's in a single commit, then reviews can skim through similar no-brainers more easily and with less risk of missing more complex changes such as rewordings).

[orpheuslummis]

LGTM! Cheers for taking the time to do this. One suggestion I would offer for the future however is to group changes under different commits - would make reviewing a bit easier (e.g. lets=>let's in a single commit, then reviews can skim through similar no-brainers more easily and with less risk of missing more complex changes such as rewordings).

I agree! I've always appreciated when you do it. Thanks