move examples/readme to testable godoc examples

[bashbunni]

We have tests for the examples given in the README, but it would probably make sense to just document those as runnable examples in the godoc. They will be more useful to users as the example will be viewable from the godoc, but will also run as part of the test suite.

https://go.dev/blog/examples

Will create an issue from this when ready to fix