Let's add some code docs

The documentation in the readme is good enough for people to understand the purpose of the library and how to use it, however the code itself is largely without documentation and this might be putting off potential contributors / bug reporters.

I suggest [YARD](http://yardoc.org/) unless anyone has a better idea. Thoughts, anyone?
