Fixed a lot of documentation warnings / errors in the existing doxygen-formatted comments. It was not always clear what the correct documentation should be. I added @todo flags where I was unsure. The comments no longer generate warnings when compiled with clang++ -Wdocumentation. However, the comments may not be accurate.
Restored compiler warning.