clarify documentation and fix doc markup

[majewsky]

The initial occasion was that the example was not rendered correctly on godoc.org. Then I saw various golint warnings and fixed those too. There are also some whitespace changes in there, too, because my editor runs gofmt automatically.

[majewsky]

bump