Improve documentation

Improve documentation of public facing methods and classes. We need to up our game here. It's not bad, but I find I'm writing more context in examples I'm developing rather than just pointing to the documentation. Will also be important for public-release if we ever head down that route. @ahopkins1 Whenever you are working on the code, let's just spend some time on the documentation, with emphasis on detail required to help others understand the methods.