*: run go1.19 'go fmt' on everything and fix problems (#3031)

Go 1.19 also formats doc comments according to the new godoc syntax.
Some of our comments, especially unexported symbols did not conform to
the godoc syntax and therefore are mangled by 'go fmt'.

This PR runs 'go fmt' from go1.19 on everything and manually fixes the
problems.

See also:
	https://github.com/golang/proposal/blob/master/design/51082-godocfmt.md

_scripts/gen-cli-docs.go

@@ -1,3 +1,4 @@
+//go:build ignore
 // +build ignore
 
 package main

_scripts/gen-usage-docs.go

@@ -1,3 +1,4 @@
+//go:build ignore
 // +build ignore
 
 package main

pkg/config/split.go

@@ -12,7 +12,7 @@ import (
 
 // SplitQuotedFields is like strings.Fields but ignores spaces inside areas surrounded
 // by the specified quote character.
-// To specify a single quote use backslash to escape it: '\''
+// To specify a single quote use backslash to escape it: \'
 func SplitQuotedFields(in string, quote rune) []string {
 	type stateEnum int
 	const (

pkg/dwarf/godwarf/tree.go

@@ -193,7 +193,9 @@ func max(a, b uint64) uint64 {
 }
 
 // fuseRanges fuses rngs2 into rngs1, it's the equivalent of
+//
 //	normalizeRanges(append(rngs1, rngs2))
+//
 // but more efficient.
 func fuseRanges(rngs1, rngs2 [][2]uint64) [][2]uint64 {
 	if rangesContains(rngs1, rngs2) {

pkg/dwarf/godwarf/type.go

@@ -535,7 +535,7 @@ func (t *UnsupportedType) stringIntl(recCheck) string {
 
 func (t *UnsupportedType) String() string { return t.stringIntl(nil) }
 
-// ReadType reads the type at off in the DWARF ``info'' section.
+// ReadType reads the type at off in the DWARF “info” section.
 func ReadType(d *dwarf.Data, index int, off dwarf.Offset, typeCache map[dwarf.Offset]Type) (Type, error) {
 	typ, err := readType(d, "info", d.Reader(), off, typeCache, nil)
 	if typ != nil {

pkg/locspec/doc.go

@@ -4,6 +4,7 @@
 // Location spec examples:
 //
 //	locStr ::= <filename>:<line> | <function>[:<line>] | /<regex>/ | (+|-)<offset> | <line> | *<address>
+//
 //	* <filename> can be the full path of a file or just a suffix
 //	* <function> ::= <package>.<receiver type>.<name> | <package>.(*<receiver type>).<name> | <receiver type>.<name> | <package>.<name> | (*<receiver type>).<name> | <name>
 //	  <function> must be unambiguous

pkg/proc/bininfo.go

@@ -1633,13 +1633,15 @@ func (bi *BinaryInfo) parseDebugFrameMacho(image *Image, exe *macho.File, debugI
 	bi.parseDebugFrameGeneral(image, debugFrameBytes, "__debug_frame", debugFrameErr, ehFrameBytes, ehFrameAddr, "__eh_frame", frame.DwarfEndian(debugInfoBytes))
 }
 
-// macOSDebugFrameBugWorkaround applies a workaround for:
-//  https://github.com/golang/go/issues/25841
+// macOSDebugFrameBugWorkaround applies a workaround for [golang/go#25841]
+//
 // It finds the Go function with the lowest entry point and the first
 // debug_frame FDE, calculates the difference between the start of the
 // function and the start of the FDE and sums it to all debug_frame FDEs.
 // A number of additional checks are performed to make sure we don't ruin
 // executables unaffected by this bug.
+//
+// [golang/go#25841]: https://github.com/golang/go/issues/25841
 func (bi *BinaryInfo) macOSDebugFrameBugWorkaround() {
 	//TODO: log extensively because of bugs in the field
 	if bi.GOOS != "darwin" || bi.Arch.Name != "arm64" {
@@ -1967,8 +1969,8 @@ func (bi *BinaryInfo) loadDebugInfoMaps(image *Image, debugInfoBytes, debugLineB
 
 // LookupGenericFunc returns a map that allows searching for instantiations of generic function by specificying a function name without type parameters.
 // For example the key "pkg.(*Receiver).Amethod" will find all instantiations of Amethod:
-//  - pkg.(*Receiver[.shape.int]).Amethod"
-//  - pkg.(*Receiver[.shape.*uint8]).Amethod"
+//   - pkg.(*Receiver[.shape.int]).Amethod
+//   - pkg.(*Receiver[.shape.*uint8]).Amethod
 //   - etc.
 func (bi *BinaryInfo) LookupGenericFunc() map[string][]*Function {
 	if bi.lookupGenericFunc == nil {

pkg/proc/core/core.go

@@ -21,10 +21,12 @@ var ErrNoThreads = errors.New("no threads found in core file")
 // 0x0000000000400000  0x000000000044f000  0x0000000000000000
 // but then it's partially overwritten with an RW mapping whose data is stored
 // in the core file:
+//
 //	Type           Offset             VirtAddr           PhysAddr
 //	               FileSiz            MemSiz              Flags  Align
 //	LOAD           0x0000000000004000 0x000000000049a000 0x0000000000000000
 //	               0x0000000000002000 0x0000000000002000  RW     1000
+//
 // This can be represented in a SplicedMemory by adding the original region,
 // then putting the RW mapping on top of it.
 type splicedMemory struct {

pkg/proc/doc.go

@@ -2,8 +2,8 @@
 // the process we are debugging.
 //
 // proc implements all core functionality including:
-// * creating / attaching to a process
-// * process manipulation (step, next, continue, halt)
-// * methods to explore the memory of the process
 //
+//   - creating / attaching to a process
+//   - process manipulation (step, next, continue, halt)
+//   - methods to explore the memory of the process
 package proc

pkg/proc/eval.go

@@ -338,16 +338,16 @@ func afterLastArgAddr(vars []*Variable) uint64 {
 }
 
 // setValue writes the value of srcv to dstv.
-// * If srcv is a numerical literal constant and srcv is of a compatible type
+//   - If srcv is a numerical literal constant and srcv is of a compatible type
 //     the necessary type conversion is performed.
-// * If srcv is nil and dstv is of a nil'able type then dstv is nilled.
-// * If srcv is the empty string and dstv is a string then dstv is set to the
+//   - If srcv is nil and dstv is of a nil'able type then dstv is nilled.
+//   - If srcv is the empty string and dstv is a string then dstv is set to the
 //     empty string.
-// * If dstv is an "interface {}" and srcv is either an interface (possibly
+//   - If dstv is an "interface {}" and srcv is either an interface (possibly
 //     non-empty) or a pointer shaped type (map, channel, pointer or struct
 //     containing a single pointer field) the type conversion to "interface {}"
 //     is performed.
-// * If srcv and dstv have the same type and are both addressable then the
+//   - If srcv and dstv have the same type and are both addressable then the
 //     contents of srcv are copied byte-by-byte into dstv
 func (scope *EvalScope) setValue(dstv, srcv *Variable, srcExpr string) error {
 	srcv.loadValue(loadSingleValue)

pkg/proc/gdbserial/rr.go

@@ -2,7 +2,6 @@ package gdbserial
 
 import (
 	"bufio"
-	"bytes"
 	"fmt"
 	"io"
 	"io/ioutil"
@@ -12,8 +11,8 @@ import (
 	"strconv"
 	"strings"
 	"syscall"
-	"unicode"
 
+	"github.com/go-delve/delve/pkg/config"
 	"github.com/go-delve/delve/pkg/proc"
 )
 
@@ -248,7 +247,7 @@ func (err *ErrMalformedRRGdbCommand) Error() string {
 
 func rrParseGdbCommand(line string) rrInit {
 	port := ""
-	fields := splitQuotedFields(line)
+	fields := config.SplitQuotedFields(line, '\'')
 	for i := 0; i < len(fields); i++ {
 		switch fields[i] {
 		case "-ex":
@@ -279,63 +278,6 @@ func rrParseGdbCommand(line string) rrInit {
 	return rrInit{port: port, exe: exe}
 }
 
-// Like strings.Fields but ignores spaces inside areas surrounded
-// by single quotes.
-// To specify a single quote use backslash to escape it: '\''
-func splitQuotedFields(in string) []string {
-	type stateEnum int
-	const (
-		inSpace stateEnum = iota
-		inField
-		inQuote
-		inQuoteEscaped
-	)
-	state := inSpace
-	r := []string{}
-	var buf bytes.Buffer
-
-	for _, ch := range in {
-		switch state {
-		case inSpace:
-			if ch == '\'' {
-				state = inQuote
-			} else if !unicode.IsSpace(ch) {
-				buf.WriteRune(ch)
-				state = inField
-			}
-
-		case inField:
-			if ch == '\'' {
-				state = inQuote
-			} else if unicode.IsSpace(ch) {
-				r = append(r, buf.String())
-				buf.Reset()
-			} else {
-				buf.WriteRune(ch)
-			}
-
-		case inQuote:
-			if ch == '\'' {
-				state = inField
-			} else if ch == '\\' {
-				state = inQuoteEscaped
-			} else {
-				buf.WriteRune(ch)
-			}
-
-		case inQuoteEscaped:
-			buf.WriteRune(ch)
-			state = inQuote
-		}
-	}
-
-	if buf.Len() != 0 {
-		r = append(r, buf.String())
-	}
-
-	return r
-}
-
 // RecordAndReplay acts like calling Record and then Replay.
 func RecordAndReplay(cmd []string, wd string, quiet bool, debugInfoDirs []string, redirects [3]string) (*proc.Target, string, error) {
 	tracedir, err := Record(cmd, wd, quiet, redirects)

pkg/proc/native/ptrace_linux_386.go

@@ -47,6 +47,7 @@ func ptraceGetRegset(tid int) (regset amd64util.AMD64Xstate, err error) {
 // ptraceGetTls return the addr of tls by PTRACE_GET_THREAD_AREA for specify thread.
 // See http://man7.org/linux/man-pages/man2/ptrace.2.html for detail about PTRACE_GET_THREAD_AREA.
 // struct user_desc at https://golang.org/src/runtime/sys_linux_386.s
+//
 //	type UserDesc struct {
 //		 EntryNumber uint32
 //		 BaseAddr    uint32

pkg/proc/native/threads_linux_arm64.go

@@ -65,9 +65,10 @@ func (wpstate *watchpointState) set(idx uint8, addr, ctrl uint64) {
 // The format of this register set is described by user_hwdebug_state in
 // arch/arm64/include/uapi/asm/ptrace.h.
 // It consists of one 64bit word containing:
-//  * 1byte number of watchpoints
-//  * 1byte debug architecture version (the 4 least significant bits of ID_AA64DFR0_EL1)
-//  * 6bytes padding
+//   - 1byte number of watchpoints
+//   - 1byte debug architecture version (the 4 least significant bits of ID_AA64DFR0_EL1)
+//   - 6bytes padding
+//
 // Followed by 2 64bit words for each watchpoint, up to a maximum of 16
 // watchpoints. The first word contains the address at which the watchpoint
 // is set (DBGWVRn_EL1), the second word is the control register for the

pkg/proc/target_exec.go

@@ -963,6 +963,7 @@ func findCallInstrForRet(p Process, mem MemoryReadWriter, ret uint64, fn *Functi
 //     created by a runtime.deferreturn run
 //   - the return address of the runtime.gopanic frame if the current frame
 //     was created by a panic
+//
 // This function is used to implement reversed StepOut
 func stepOutReverse(p *Target, topframe, retframe Stackframe, sameGCond ast.Expr) error {
 	curthread := p.CurrentThread()

pkg/proc/types.go

@@ -112,12 +112,12 @@ func (ctxt *loadDebugInfoMapsContext) lookupAbstractOrigin(bi *BinaryInfo, off d
 
 // runtimeTypeToDIE returns the DIE corresponding to the runtime._type.
 // This is done in three different ways depending on the version of go.
-// * Before go1.7 the type name is retrieved directly from the runtime._type
+//   - Before go1.7 the type name is retrieved directly from the runtime._type
 //     and looked up in debug_info
-// * After go1.7 the runtime._type struct is read recursively to reconstruct
+//   - After go1.7 the runtime._type struct is read recursively to reconstruct
 //     the name of the type, and then the type's name is used to look up
 //     debug_info
-// * After go1.11 the runtimeTypeToDIE map is used to look up the address of
+//   - After go1.11 the runtimeTypeToDIE map is used to look up the address of
 //     the type and map it drectly to a DIE.
 func runtimeTypeToDIE(_type *Variable, dataAddr uint64) (typ godwarf.Type, kind int64, err error) {
 	bi := _type.bi

service/dap/server.go

@@ -1705,9 +1705,10 @@ func (s *Session) onThreadsRequest(request *dap.ThreadsRequest) {
 // onAttachRequest handles 'attach' request.
 // This is a mandatory request to support.
 // Attach debug sessions support the following modes:
-// -- [DEFAULT] "local" -- attaches debugger to a local running process
+//
+//   - [DEFAULT] "local" -- attaches debugger to a local running process.
 //     Required args: processID
-// -- "remote" - attaches client to a debugger already attached to a process
+//   - "remote" -- attaches client to a debugger already attached to a process.
 //     Required args: none (host/port are used externally to connect)
 func (s *Session) onAttachRequest(request *dap.AttachRequest) {
 	var args AttachConfig = defaultAttachConfig // narrow copy for initializing non-zero default values
@@ -2591,12 +2592,15 @@ func (s *Session) convertVariableWithOpts(v *proc.Variable, qualifiedNameOrExpr
 // onEvaluateRequest handles 'evalute' requests.
 // This is a mandatory request to support.
 // Support the following expressions:
-// -- {expression} - evaluates the expression and returns the result as a variable
-// -- call {function} - injects a function call and returns the result as a variable
-// -- config {expression} - updates configuration parameters
+//
+//   - {expression} - evaluates the expression and returns the result as a variable
+//   - call {function} - injects a function call and returns the result as a variable
+//   - config {expression} - updates configuration parameters
+//
 // TODO(polina): users have complained about having to click to expand multi-level
 // variables, so consider also adding the following:
-// -- print {expression} - return the result as a string like from dlv cli
+//
+//   - print {expression} - return the result as a string like from dlv cli
 func (s *Session) onEvaluateRequest(request *dap.EvaluateRequest) {
 	showErrorToUser := request.Arguments.Context != "watch" && request.Arguments.Context != "repl" && request.Arguments.Context != "hover"
 	if s.debugger == nil {
@@ -3301,6 +3305,7 @@ func (s *Session) getExprString(expr string, goroutineID, frame int) (string, er
 }
 
 // sendErrorResponseWithOpts offers configuration options.
+//
 //	showUser - if true, the error will be shown to the user (e.g. via a visible pop-up)
 func (s *Session) sendErrorResponseWithOpts(request dap.Request, id int, summary, details string, showUser bool) {
 	er := &dap.ErrorResponse{}
@@ -3706,6 +3711,7 @@ type logMessage struct {
 }
 
 // parseLogPoint parses a log message according to the DAP spec:
+//
 //	"Expressions within {} are interpolated."
 func parseLogPoint(msg string) (bool, *logMessage, error) {
 	// Note: All braces *must* come in pairs, even those within an

service/dap/server_test.go

@@ -321,7 +321,8 @@ func TestForceStopWhileStopping(t *testing.T) {
 
 // TestLaunchStopOnEntry emulates the message exchange that can be observed with
 // VS Code for the most basic launch debug session with "stopOnEntry" enabled:
-// - User selects "Start Debugging":  1 >> initialize
+//
+//	User selects "Start Debugging":  1 >> initialize
 //	                              :  1 << initialize
 //	                              :  2 >> launch
 //	                              :    << initialized event
@@ -331,7 +332,7 @@ func TestForceStopWhileStopping(t *testing.T) {
 //	                              :  4 >> setExceptionBreakpoints (empty)
 //	                              :  4 << setExceptionBreakpoints
 //	                              :  5 >> configurationDone
-// - Program stops upon launching  :    << stopped event
+//	Program stops upon launching  :    << stopped event
 //	                              :  5 << configurationDone
 //	                              :  6 >> threads
 //	                              :  6 << threads (Dummy)
@@ -341,17 +342,18 @@ func TestForceStopWhileStopping(t *testing.T) {
 //	                              :  8 << error (Unable to produce stack trace)
 //	                              :  9 >> stackTrace
 //	                              :  9 << error (Unable to produce stack trace)
-// - User evaluates bad expression : 10 >> evaluate
+//	User evaluates bad expression : 10 >> evaluate
 //	                              : 10 << error (unable to find function context)
-// - User evaluates good expression: 11 >> evaluate
+//	User evaluates good expression: 11 >> evaluate
 //	                              : 11 << evaluate
-// - User selects "Continue"       : 12 >> continue
+//	User selects "Continue"       : 12 >> continue
 //	                              : 12 << continue
-// - Program runs to completion    :    << terminated event
+//	Program runs to completion    :    << terminated event
 //	                              : 13 >> disconnect
 //	                              :    << output event (Process exited)
 //	                              :    << output event (Detaching)
 //	                              : 13 << disconnect
+//
 // This test exhaustively tests Seq and RequestSeq on all messages from the
 // server. Other tests do not necessarily need to repeat all these checks.
 func TestLaunchStopOnEntry(t *testing.T) {
@@ -801,6 +803,7 @@ func TestPreSetBreakpoint(t *testing.T) {
 }
 
 // checkStackFramesExact is a helper for verifying the values within StackTraceResponse.
+//
 //	wantStartName - name of the first returned frame (ignored if "")
 //	wantStartLine - file line of the first returned frame (ignored if <0).
 //	wantStartID - id of the first frame returned (ignored if wantFrames is 0).
@@ -956,6 +959,7 @@ func checkStackFramesNamed(testName string, t *testing.T, got *dap.StackTraceRes
 }
 
 // checkScope is a helper for verifying the values within a ScopesResponse.
+//
 //	i - index of the scope within ScopesRespose.Body.Scopes array
 //	name - name of the scope
 //	varRef - reference to retrieve variables of this scope. If varRef is negative, the reference is not checked.
@@ -971,6 +975,7 @@ func checkScope(t *testing.T, got *dap.ScopesResponse, i int, name string, varRe
 }
 
 // checkChildren is a helper for verifying the number of variables within a VariablesResponse.
+//
 //	parentName - pseudoname of the enclosing variable or scope (used for error message only)
 //	numChildren - number of variables/fields/elements of this variable
 func checkChildren(t *testing.T, got *dap.VariablesResponse, parentName string, numChildren int) {
@@ -984,6 +989,7 @@ func checkChildren(t *testing.T, got *dap.VariablesResponse, parentName string,
 }
 
 // checkVar is a helper for verifying the values within a VariablesResponse.
+//
 //	i - index of the variable within VariablesRespose.Body.Variables array (-1 will search all vars for a match)
 //	name - name of the variable
 //	evalName - fully qualified variable name or alternative expression to load this variable
@@ -3756,6 +3762,7 @@ func TestWorkingDir(t *testing.T) {
 }
 
 // checkEval is a helper for verifying the values within an EvaluateResponse.
+//
 //	value - the value of the evaluated expression
 //	hasRef - true if the evaluated expression should have children and therefore a non-0 variable reference
 //	ref - reference to retrieve children of this evaluated expression (0 if none)
@@ -3768,6 +3775,7 @@ func checkEval(t *testing.T, got *dap.EvaluateResponse, value string, hasRef boo
 }
 
 // checkEvalIndexed is a helper for verifying the values within an EvaluateResponse.
+//
 //	value - the value of the evaluated expression
 //	hasRef - true if the evaluated expression should have children and therefore a non-0 variable reference
 //	ref - reference to retrieve children of this evaluated expression (0 if none)
@@ -5089,6 +5097,7 @@ type onBreakpoint struct {
 // runDebugSessionWithBPs is a helper for executing the common init and shutdown
 // sequences for a program that does not stop on entry
 // while specifying breakpoints and unique launch/attach criteria via parameters.
+//
 //	cmd            - "launch" or "attach"
 //	cmdRequest     - a function that sends a launch or attach request,
 //	                 so the test author has full control of its arguments.

service/dap/types.go

@@ -7,20 +7,30 @@ import (
 )
 
 // Launch debug sessions support the following modes:
+//
 //	-- [DEFAULT] "debug" - builds and launches debugger for specified program (similar to 'dlv debug')
+//
 //	   Required args: program
 //	   Optional args with default: output, cwd, noDebug
 //	   Optional args: buildFlags, args
+//
 //	-- "test" - builds and launches debugger for specified test (similar to 'dlv test')
+//
 //	   same args as above
+//
 //	-- "exec" - launches debugger for precompiled binary (similar to 'dlv exec')
+//
 //	   Required args: program
 //	   Optional args with default: cwd, noDebug
 //	   Optional args: args
+//
 //	-- "replay" - replays a trace generated by mozilla rr. Mozilla rr must be installed.
+//
 //	   Required args: traceDirPath
 //	   Optional args: args
+//
 //	-- "core" - examines a core dump (only supports linux and windows core dumps).
+//
 //	   Required args: program, coreFilePath
 //	   Optional args: args
 //

service/rpc2/server.go

@@ -632,15 +632,21 @@ type ListGoroutinesOut struct {
 // If arg.Filters are specified the list of returned goroutines is filtered
 // applying the specified filters.
 // For example:
+//
 //	ListGoroutinesFilter{ Kind: ListGoroutinesFilterUserLoc, Negated: false, Arg: "afile.go" }
+//
 // will only return goroutines whose UserLoc contains "afile.go" as a substring.
 // More specifically a goroutine matches a location filter if the specified
 // location, formatted like this:
+//
 //	filename:lineno in function
+//
 // contains Arg[0] as a substring.
 //
 // Filters can also be applied to goroutine labels:
+//
 //	ListGoroutineFilter{ Kind: ListGoroutinesFilterLabel, Negated: false, Arg: "key=value" }
+//
 // this filter will only return goroutines that have a key=value label.
 //
 // If arg.GroupBy is not GoroutineFieldNone then the goroutines will
@@ -703,7 +709,7 @@ type FindLocationOut struct {
 //	loc ::= <filename>:<line> | <function>[:<line>] | /<regex>/ | (+|-)<offset> | <line> | *<address>
 //	* <filename> can be the full path of a file or just a suffix
 //	* <function> ::= <package>.<receiver type>.<name> | <package>.(*<receiver type>).<name> | <receiver type>.<name> | <package>.<name> | (*<receiver type>).<name> | <name>
-//  * <function> must be unambiguous
+//	  <function> must be unambiguous
 //	* /<regex>/ will return a location for each function matched by regex
 //	* +<offset> returns a location for the line that is <offset> lines after the current line
 //	* -<offset> returns a location for the line that is <offset> lines before the current line

service/rpccommon/server.go

@@ -213,6 +213,7 @@ func isExportedOrBuiltinType(t reflect.Type) bool {
 // available through the RPC interface.
 // These are all the public methods of rcvr that have one of those
 // two signatures:
+//
 //	func (rcvr ReceiverType) Method(in InputType, out *ReplyType) error
 //	func (rcvr ReceiverType) Method(in InputType, cb service.RPCCallback)
 func suitableMethods(rcvr interface{}, methods map[string]*methodType, log *logrus.Entry) {