README improvements

Separated out from #173
Why the :: notation here? The function calls are not really in a namespace.