Review code documentation

[dblnz]

The documentation in the code should be reviewed to ensure it is up to date with the code it describes.
This is particularly helpful for newcomers as sometimes understanding what and why is happening in some parts of the codebase can require additional information.

This can/should be split into multiple smaller issues to address specific parts of the codebase.