In some cases the documentation for functions in this package was
lacking from the beginning and, in order cases, the documentation didn't
keep pace as the package grew.

This change somewhat addresses that.

Updates #13711.

Change-Id: I25b2bb1fcd4658c5417671e23cf8e644d08cb9ab
Reviewed-on: https://go-review.googlesource.com/18486Reviewed-by: Rob Pike <r@golang.org>
Reviewed-by: Andrew Gerrand <adg@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org>