go/token: rename RemoveLine to MergeLine, improve documentation

This is a follow-up to feedback from gri in
https://golang.org/cl/12837044/. Most of the wording
and naming improvements are lifted shamelessly from him.

R=gri
CC=golang-dev
https://golang.org/cl/13670043

2 files changed, 20 insertions, 6 deletions

diff --git a/src/pkg/go/ast/import.go b/src/pkg/go/ast/import.go
index 7c34d491b7..d2770d16cf 100644
--- a/src/pkg/go/ast/import.go
+++ b/src/pkg/go/ast/import.go
@@ -44,7 +44,7 @@ func SortImports(fset *token.FileSet, f *File) {
 			lastSpec := d.Specs[len(d.Specs)-1]
 			lastLine := fset.Position(lastSpec.Pos()).Line
 			if rParenLine := fset.Position(d.Rparen).Line; rParenLine > lastLine+1 {
-				fset.File(d.Rparen).RemoveLine(rParenLine - 1)
+				fset.File(d.Rparen).MergeLine(rParenLine - 1)
 			}
 		}
 	}
@@ -146,7 +146,7 @@ func sortSpecs(fset *token.FileSet, f *File, specs []Spec) []Spec {
 			deduped = append(deduped, s)
 		} else {
 			p := s.Pos()
-			fset.File(p).RemoveLine(fset.Position(p).Line)
+			fset.File(p).MergeLine(fset.Position(p).Line)
 		}
 	}
 	specs = deduped
diff --git a/src/pkg/go/token/position.go b/src/pkg/go/token/position.go
index 44b938319c..e6f0ae6a67 100644
--- a/src/pkg/go/token/position.go
+++ b/src/pkg/go/token/position.go
@@ -97,7 +97,7 @@ type File struct {
 	size int    // file size as provided to AddFile
 
 	// lines and infos are protected by set.mutex
-	lines []int
+	lines []int // lines contains the offset of the first character for each line (the first entry is always 0)
 	infos []lineInfo
 }
 
@@ -136,13 +136,27 @@ func (f *File) AddLine(offset int) {
 	f.set.mutex.Unlock()
 }
 
-// RemoveLine removes a line by line number as reported by Position.Line.
+// MergeLine merges a line with the following line. It is akin to replacing
+// the newline character at the end of the line with a space (to not change the
+// remaining offsets). To obtain the line number, consult e.g. Position.Line.
+// MergeLine will panic if given an invalid line number.
 //
-func (f *File) RemoveLine(line int) {
+func (f *File) MergeLine(line int) {
+	if line <= 0 {
+		panic("illegal line number (line numbering starts at 1)")
+	}
 	f.set.mutex.Lock()
+	defer f.set.mutex.Unlock()
+	if line >= len(f.lines) {
+		panic("illegal line number")
+	}
+	// To merge the line numbered <line> with the line numbered <line+1>,
+	// we need to remove the entry in lines corresponding to the line
+	// numbered <line+1>. The entry in lines corresponding to the line
+	// numbered <line+1> is located at index <line>, since indices in lines
+	// are 0-based and line numbers are 1-based.
 	copy(f.lines[line:], f.lines[line+1:])
 	f.lines = f.lines[:len(f.lines)-1]
-	f.set.mutex.Unlock()
 }
 
 // SetLines sets the line offsets for a file and returns true if successful.