Write better documentation

[fabdrol]

Current readme is just a bunch of examples. Need to expand:

• Provide list of all available functions, and what they do.
• Provide examples for various features, in separate code blocks
• Provide usage guidance
• Add links to specification where relevant