Dev/improve documentation

Added/modified some documentation which helped me get oriented when working with the code.
Modified some doxygen control words that did not work well for me.
Maybe there should be a "logging" message to std::cerr here?  Or maybe just a TODO in the comment to add a logging message in the future when logging is supported?