Documentation improvements:

 - merged efficiency into a section of usage
 - split reference up into useful sections (documentation could still be expanded
 - documented a huge amount of the API

happy to be merged and get feedback where to improve