*: Add some more documentation to exported types and methods

pkg/dwarf/op/op.go

@@ -10,6 +10,8 @@ import (
 	"github.com/go-delve/delve/pkg/dwarf/util"
 )
 
+// Opcode represent a DWARF stack program instruction.
+// See ./opcodes.go for a full list.
 type Opcode byte
 
 //go:generate go run ../../../scripts/gen-opcodes.go opcodes.table opcodes.go
@@ -76,7 +78,7 @@ func ExecuteStackProgram(regs DwarfRegisters, instructions []byte, ptrSize int)
 	return ctxt.stack[len(ctxt.stack)-1], nil, nil
 }
 
-// PrettyPrint prints instructions to out.
+// PrettyPrint prints the DWARF stack program instructions to `out`.
 func PrettyPrint(out io.Writer, instructions []byte) {
 	in := bytes.NewBuffer(instructions)
 

pkg/dwarf/op/regs.go

@@ -5,6 +5,7 @@ import (
 	"encoding/binary"
 )
 
+// DwarfRegisters holds the value of stack program registers.
 type DwarfRegisters struct {
 	StaticBase uint64
 

pkg/proc/amd64_arch.go

@@ -110,15 +110,15 @@ func (a *AMD64) FixFrameUnwindContext(fctxt *frame.FrameContext, pc uint64, bi *
 		return &frame.FrameContext{
 			RetAddrReg: amd64DwarfIPRegNum,
 			Regs: map[uint64]frame.DWRule{
-				amd64DwarfIPRegNum: frame.DWRule{
+				amd64DwarfIPRegNum: {
 					Rule:   frame.RuleOffset,
 					Offset: int64(-a.PtrSize()),
 				},
-				amd64DwarfBPRegNum: frame.DWRule{
+				amd64DwarfBPRegNum: {
 					Rule:   frame.RuleOffset,
 					Offset: int64(-2 * a.PtrSize()),
 				},
-				amd64DwarfSPRegNum: frame.DWRule{
+				amd64DwarfSPRegNum: {
 					Rule:   frame.RuleValOffset,
 					Offset: 0,
 				},
@@ -426,6 +426,7 @@ func (a *AMD64) AddrAndStackRegsToDwarfRegisters(staticBase, pc, sp, bp, lr uint
 	}
 }
 
+// DwarfRegisterToString returns the name and value representation of the given register.
 func (a *AMD64) DwarfRegisterToString(i int, reg *op.DwarfRegister) (name string, floatingPoint bool, repr string) {
 	name, ok := amd64DwarfToName[i]
 	if !ok {

pkg/proc/arch.go

@@ -8,20 +8,43 @@ import (
 // Arch defines an interface for representing a
 // CPU architecture.
 type Arch interface {
+	// PtrSize returns the size of a pointer for the architecture.
 	PtrSize() int
+	// MaxInstructionLength is the maximum size in bytes of an instruction.
 	MaxInstructionLength() int
+	// AsmDecode decodes the assembly instruction starting at mem[0:] into asmInst.
+	// It assumes that the Loc and AtPC fields of asmInst have already been filled.
 	AsmDecode(asmInst *AsmInstruction, mem []byte, regs Registers, memrw MemoryReadWriter, bi *BinaryInfo) error
+	// Prologues returns a list of stack split prologues
+	// that are inserted at function entry.
 	Prologues() []opcodeSeq
+	// BreakpointInstruction is the instruction that will trigger a breakpoint trap for
+	// the given architecture.
 	BreakpointInstruction() []byte
+	// BreakInstrMovesPC is true if hitting the breakpoint instruction advances the
+	// instruction counter by the size of the breakpoint instruction.
 	BreakInstrMovesPC() bool
+	// BreakpointSize is the size of the breakpoint instruction for the given architecture.
 	BreakpointSize() int
+	// DerefTLS is true if the G struct stored in the TLS section is a pointer
+	// and the address must be dereferenced to find to actual G struct.
 	DerefTLS() bool
+	// FixFrameUnwindContext applies architecture specific rules for unwinding a stack frame
+	// on the given arch.
 	FixFrameUnwindContext(*frame.FrameContext, uint64, *BinaryInfo) *frame.FrameContext
+	// SwitchStack will use the current frame to determine if it's time to
+	// switch between the system stack and the goroutine stack or vice versa.
 	SwitchStack(it *stackIterator, callFrameRegs *op.DwarfRegisters) bool
+	// RegSize returns the size (in bytes) of register regnum.
 	RegSize(uint64) int
+	// RegistersToDwarfRegisters maps hardware registers to DWARF registers.
 	RegistersToDwarfRegisters(uint64, Registers) op.DwarfRegisters
+	// AddrAndStackRegsToDwarfRegisters returns DWARF registers from the passed in
+	// PC, SP, and BP registers in the format used by the DWARF expression interpreter.
 	AddrAndStackRegsToDwarfRegisters(uint64, uint64, uint64, uint64, uint64) op.DwarfRegisters
+	// DwarfRegisterToString returns the name and value representation of the given register.
 	DwarfRegisterToString(int, *op.DwarfRegister) (string, bool, string)
+	// InhibitStepInto returns whether StepBreakpoint can be set at pc.
 	InhibitStepInto(bi *BinaryInfo, pc uint64) bool
 }
 

pkg/proc/i386_disasm.go

@@ -14,6 +14,8 @@ func (i *I386) AsmDecode(asmInst *AsmInstruction, mem []byte, regs Registers, me
 	return x86AsmDecode(asmInst, mem, regs, memrw, bi, 32)
 }
 
+// Prologues returns a list of stack split prologues
+// that are inserted at function entry.
 func (i *I386) Prologues() []opcodeSeq {
 	return prologuesI386
 }

pkg/proc/registers.go

@@ -33,10 +33,14 @@ type Register struct {
 	Reg  *op.DwarfRegister
 }
 
+// AppendUint64Register will create a new Register struct with the name and value
+// specified and append it to the `regs` slice.
 func AppendUint64Register(regs []Register, name string, value uint64) []Register {
 	return append(regs, Register{name, op.DwarfRegisterFromUint64(value)})
 }
 
+// AppendBytesRegister will create a new Register struct with the name and value
+// specified and append it to the `regs` slice.
 func AppendBytesRegister(regs []Register, name string, value []byte) []Register {
 	return append(regs, Register{name, op.DwarfRegisterFromBytes(value)})
 }