replace python docs with Go example tests

I cleaned up the docs according to the godoc formatting rules and removed python annotations.

I translated the code examples to Go and put them in example_test.go for better formatting in godoc. 
would you mind converting this (and below) to a single-line comment?

/**/ -> //