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

diff --git a/src/pkg/go/ast/import.go b/src/pkg/go/ast/import.go
index 7c34d491b73c8031230e12c28883819aa0135e25..d2770d16cf862b8346832ee985a3bfb2624e051b 100644 (file)
--- 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 44b938319cec956110e0466de205b3bdd52decf8..e6f0ae6a6738f7c33e2581c8b51870838aa3177d 100644 (file)
--- 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.