Documentation improvements

Created by: anjos

This was a request on #104 (closed) that was moved here.

The user guide is already fairly good. I would not say the same about the documentation of the python bindings that show up when using the help() function of python. For many functions/classes, this documentation is very limited and unhelpful.

In particular these are some guidelines for constructing documentation (in order of priority)

1. Make sure that your class shows up at the Tutorials. It is the first entry point for most people

2. Make sure the Python reference documentation of your class mentions references and explains what the class is about. De-construct acronyms and insert equations and explanations when it makes sense.

3. Document the header files of your C++ if you have any. These are important for core developers.

4. Document the code itself - these are important for debugging.