gopls/internal/lsp: more comment tweaks post-//line support

Change-Id: Ia44de7449fd0d60112dd71e372813bd8b3846175
Reviewed-on: https://go-review.googlesource.com/c/tools/+/458556
TryBot-Result: Gopher Robot <[email protected]>
Reviewed-by: Robert Findley <[email protected]>
gopls-CI: kokoro <[email protected]>
Run-TryBot: Alan Donovan <[email protected]>

Author: adonovan

gopls/internal/lsp/protocol/span.go

@@ -29,8 +29,7 @@
 // TODO(adonovan): simplify this picture. Eliminate the optionality of
 // span.{Span,Point}'s position and offset fields: work internally in
 // terms of offsets (like span.Range), and require a mapper to convert
-// them to protocol (UTF-16) line/col form. Stop honoring //line
-// directives.
+// them to protocol (UTF-16) line/col form.
 
 package protocol
 
@@ -162,7 +161,6 @@ func (m *ColumnMapper) Position(p span.Point) (Position, error) {
 // offset within m.Content.
 func (m *ColumnMapper) OffsetPosition(offset int) (Position, error) {
 	// We use span.ToPosition for its "line+1 at EOF" workaround.
-	// TODO(adonovan): ToPosition honors //line directives. It probably shouldn't.
 	line, _, err := span.ToPosition(m.TokFile, offset)
 	if err != nil {
 		return Position{}, fmt.Errorf("OffsetPosition: %v", err)

gopls/internal/lsp/source/util.go

@@ -26,20 +26,16 @@ import (
 // MappedRange provides mapped protocol.Range for a span.Range, accounting for
 // UTF-16 code points.
 //
-// TOOD(adonovan): eliminate this type. All callers need either m, or a protocol.Range.
+// TOOD(adonovan): eliminate this type. Replace all uses by an
+// explicit pair (span.Range, protocol.ColumnMapper), and an operation
+// to map both to a protocol.Range.
 type MappedRange struct {
 	spanRange span.Range             // the range in the compiled source (package.CompiledGoFiles)
 	m         *protocol.ColumnMapper // a mapper of the edited source (package.GoFiles)
 }
 
-// NewMappedRange returns a MappedRange for the given file and valid start/end token.Pos.
-//
-// By convention, start and end are assumed to be positions in the compiled (==
-// type checked) source, whereas the column mapper m maps positions in the
-// user-edited source. Note that these may not be the same, as when using goyacc or CGo:
-// CompiledGoFiles contains generated files, whose positions (via
-// token.File.Position) point to locations in the edited file -- the file
-// containing `import "C"`.
+// NewMappedRange returns a MappedRange for the given file and
+// start/end positions, which must be valid within m.TokFile.
 func NewMappedRange(m *protocol.ColumnMapper, start, end token.Pos) MappedRange {
 	return MappedRange{
 		spanRange: span.NewRange(m.TokFile, start, end),