go/token: explain file base offset better in documentation
Fixes #36648.
Change-Id: I92d4462fea0079f63697fb8f407fd2d50b7d68f7
Reviewed-on: https://go-review.googlesource.com/c/go/+/238117
Reviewed-by: Ian Lance Taylor <iant@golang.org>
diff --git a/src/go/token/position.go b/src/go/token/position.go
index 3f5a390..d0dbc29 100644
--- a/src/go/token/position.go
+++ b/src/go/token/position.go
@@ -58,8 +58,11 @@
// larger, representation.
//
// The Pos value for a given file is a number in the range [base, base+size],
-// where base and size are specified when adding the file to the file set via
-// AddFile.
+// where base and size are specified when a file is added to the file set.
+// The difference between a Pos value and the corresponding file base
+// corresponds to the byte offset of that position (represented by the Pos value)
+// from the beginning of the file. Thus, the file base offset is the Pos value
+// representing the first byte in the file.
//
// To create the Pos value for a specific source offset (measured in bytes),
// first add the respective file to the current file set using FileSet.AddFile
@@ -364,6 +367,22 @@
// Methods of file sets are synchronized; multiple goroutines
// may invoke them concurrently.
//
+// The byte offsets for each file in a file set are mapped into
+// distinct (integer) intervals, one interval [base, base+size]
+// per file. Base represents the first byte in the file, and size
+// is the corresponding file size. A Pos value is a value in such
+// an interval. By determining the interval a Pos value belongs
+// to, the file, its file base, and thus the byte offset (position)
+// the Pos value is representing can be computed.
+//
+// When adding a new file, a file base must be provided. That can
+// be any integer value that is past the end of any interval of any
+// file already in the file set. For convenience, FileSet.Base provides
+// such a value, which is simply the end of the Pos interval of the most
+// recently added file, plus one. Unless there is a need to extend an
+// interval later, using the FileSet.Base should be used as argument
+// for FileSet.AddFile.
+//
type FileSet struct {
mutex sync.RWMutex // protects the file set
base int // base offset for the next file
