text/scanner: improve documentation

LGTM=r
R=r
CC=golang-codereviews
https://codereview.appspot.com/123390043