Improve documentation

[DanRStevens]

We should try to improve the API documentation. Currently we have a lot of "low value" comments, which I've sometimes taken to just removing as they only add clutter, without telling people anything new. Examples would be comments that simply restate what's already implied by a class or variable name.

In some cases, we should improve class or variable names so there is no need to document what they are for. Ideally a variable's use should be self evident from it's name, and so not require documentation.

For functions and classes, we should try to give examples of usage whenever possible. To some extent, the unit test code serves as example usage, though that's not an obvious place for people to look. Actually, I wonder if there might be a way for Doxygen to pick up certain blocks of unit test code and display it as part of the documentation. That might be a good way of having up-to-date documentation that is guaranteed to compile and function as expected. Since the unit tests are regularly run as part of CI, the code there should always be up-to-date.