Improve documentation, add examples

[Svalorzen]

While each method & related code is well commented, I'd like more examples on how to use the library, and possibly explanations of the underlying algorithms.

I'm very open to contributions for this. I think that if somebody else can write the documentation it will be much more helpful than if I write it myself, given that already know how the code works and is thus much harder for me to guess what are the pain points for new users.

If you feel like helping out, I'd be very glad to help you along.