text/scanner: clarify documentation on Pos and Position

For #20292. (See discussion in that issue.)

Change-Id: I44cd69394fc47a01776905ec34305ba524c89883
Reviewed-on: https://go-review.googlesource.com/43452Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

src/text/scanner/scanner.go

@@ -166,7 +166,8 @@ type Scanner struct {
 	// The Filename field is always left untouched by the Scanner.
 	// If an error is reported (via Error) and Position is invalid,
 	// the scanner is not inside a token. Call Pos to obtain an error
-	// position in that case.
+	// position in that case, or to obtain the position immediately
+	// after the most recently scanned token.
 	Position
 }
 
@@ -637,6 +638,8 @@ redo:
 
 // Pos returns the position of the character immediately after
 // the character or token returned by the last call to Next or Scan.
+// Use the Scanner's Position field for the start position of the most
+// recently scanned token.
 func (s *Scanner) Pos() (pos Position) {
 	pos.Filename = s.Filename
 	pos.Offset = s.srcBufOffset + s.srcPos - s.lastCharLen