extend docs and add more examples

[effinsky]

this lib would surely see more use -- which I am all in favor of -- if it had more extensive docs and some more examples. let's consider adding some.