Please improve the documentation

[damien122]

Please improve the documentation.
The current documentation is really not enough. I can't understand any thing. And all methods have no documentation header. So when I want to use one function, I don't know what it do and what are there parameters.

[tgjones]

I'd gladly accept pull requests to improve the documentation.

I'm going to close this issue though, because it's just going to sit here not getting done - not because I disagree with the idea, which is a good one.