Improve code documentation

[drichards2]

There's very little in the way of code documentation at the moment - it would be a good thing to do, especially if there's going to be a big 'go live' event.

[drichards2]

(Realised this was existing and pre-dated #53 )