Documentation

[jonblack]

The library is getting a little more complex and the examples probably won't be enough to help newcomers.

Write some documentation and stick it up on readthedocs.org

[eadf]

How about first adding documentation of each method in the header file?
The header file is, after all, the first place where we usually look for API documentation.

If the header file has, for example, doxygen comments the generated files can be used as a base for higher level documentation at third-party sites.

[jonblack]

I've started added some doxygen style comments already. But you're right, that should be done here as well.