Add comments to document the code

Also add some FIXME markers in places where the code needs more
explanation.
Complete function documentation

- Complete the code documentation effort started by @lucc
- Remove some judgemental comments :sparkles:
- Remove comments pertaining to things that should be opened as issues
- Boxed :exclamation: