[major] make API more idiomatic, make go vet and golint happy and modify examples accordingly