> I do wish the documentation convention included not only a brief description each function, etc., but also a brief example.

It is getting there. If you run godoc locally with tip, you will find many more examples than there were previously.

See http://golang.org/pkg/path/ for a current example. And the source for those examples can be found here: http://golang.org/src/pkg/path/example_test.go. Note that this technique will work for your own packages as well.

The technology is there, the implementation is still incomplete; but more progress has been made than is easily visible.