Add docs.
Give it a more natural signature.

Passes toolstash -cmp.

Change-Id: Iab368dd10e8f16e41b725c2980020bbead2cdefb
Reviewed-on: https://go-review.googlesource.com/26756
Run-TryBot: Josh Bleecher Snyder <josharian@gmail.com>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>