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/43452
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/text/scanner/scanner.go b/src/text/scanner/scanner.go
index e085f8a7d956bb2ee432254c4a8790c729d45bea..6fb0422fe5e9d84894dd0acc35af522915e34dfa 100644 (file)
--- a/src/text/scanner/scanner.go
+++ b/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