Documentation for the library

We need better documentation to start making it easy for people to use our library.

Ideally parts of the documentation will be built from source comments.
Other parts such as examples would be separate from the source code.
