fix example function definitions
update Readme
Provide proper synopsis for godoc