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
why would SamTag behave differently from Cigar, BaseQual and ReadBases?