Developer documentation updates

* Doxygen: fix all the warnings in the doxygen system
* Docs: add warnings to API operations that create non-trivial objects for user awareness

closes #158
These warnings you've added are incorrect. The SamTag getters DO copy the underlying values.