Documentation clean up

- Clean up malformed doxygen comments
- Added some more documentation
- Activate inherit docs in the doxygen conf
- Moved some doc comments from the front facing objects to the respective interfaces
- Removed some redundant comments 

It would be really great if some one could look out for typos and other mistakes. 
We probably should also document what 'copying' means in our framework, i.e. the semantics, e.g. that we only 'copy' the shared pointer and such (otherwise the whole docu here is a bit pointless ;-) ).