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
But the comment should be changed regardless, to reflect current reality.