[dev.inline] cmd/compile/internal/syntax: use syntax.Pos for all external positions

- use syntax.Pos in syntax.Error (rather than line, col)
- use syntax.Pos in syntax.PragmaHandler (rather than just line)
- update uses
- better documentation in various places

Also:
- make Pos methods use Pos receiver (rather than *Pos)

Reviewed in and cherry-picked from https://go-review.googlesource.com/#/c/33891/.
With minor adjustments to noder.go to make merge compile.

Change-Id: I5507cea6c2be46a7677087c1aeb69382d31033eb
Reviewed-on: https://go-review.googlesource.com/34236
Reviewed-by: Matthew Dempsky <mdempsky@google.com>

1 files changed, 12 insertions, 0 deletions

diff --git a/src/cmd/compile/internal/syntax/scanner.go b/src/cmd/compile/internal/syntax/scanner.go
index c31611a96d..8af2f1ce14 100644
--- a/src/cmd/compile/internal/syntax/scanner.go
+++ b/src/cmd/compile/internal/syntax/scanner.go
@@ -41,6 +41,18 @@ func (s *scanner) init(src io.Reader, errh, pragh func(line, col uint, msg strin
 	s.nlsemi = false
 }
 
+// next advances the scanner by reading the next token.
+//
+// If a read, source encoding, or lexical error occurs, next
+// calls the error handler installed with init. The handler
+// must exist.
+//
+// If a //line or //go: directive is encountered, next
+// calls the pragma handler installed with init, if not nil.
+//
+// The (line, col) position passed to the error and pragma
+// handler is always at or after the current source reading
+// position.
 func (s *scanner) next() {
 	nlsemi := s.nlsemi
 	s.nlsemi = false