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. 
I am not sure the user of the API documentation will have an understanding of what a 'null entity' is. We should probably document the semantics of such objects somewhere and then refer to it every time.