Add docblocks with descriptions to methods.

[hailwood]

We do a fairly good job of documenting the methods in the readme.md.
But it's a bit frustrating having to go to the readme to make sure I'm using the right method.

If we added those descriptions to the code as docblocks then our IDE can tell us right there.