Improve documentation

[opieters]

The documentation is still incomplete and not always very clear. This should be improved for the next big release. Furthermore, the source code itself is poorly documented. This should also be improved to make it easier for others to contribute and build upon this package.