Add, improve and consolidate API documentation

[ggraffieti]

Before releasing our project to the public, the API should be well documented and easy to understand.

• In many parts of the project the documentation is totally lacking or is very poor. Every class, function and public method should be well documented, with a completely description of parameters, return value etc.
• In some part of the project the documentation exists, but it's incomplete or should be improved.
• The documentation style is inconsistent, in some part is written in the reST (reStructuredText) format, in other part in the Google style format. We've chosen reST as the preferred code documentation style, so a conversion of all the apidoc in reST is necessary.

[vlomonaco]

We should fix all around the declaration of class attributes.
If they are only created inside the __init__ method they won't appear in the doc.

[vlomonaco]

This is too general, moving it to discussion. We will make more actionable items.