More comprehensive docblock documentation

[nickdaugherty]

There are a variety of undocumented (or lightly documented) functions and classes - we should flesh out the docblock documentation

[simonwheatley]

Noting that we're calling this issue optional for the Code Review milestone.