dwarf/*: add godoc comments (#2265)

pkg/dwarf/dwarfbuilder/builder.go

@@ -9,6 +9,7 @@ import (
 	"fmt"
 )
 
+// Builder dwarf builder
 type Builder struct {
 	info     bytes.Buffer
 	loc      bytes.Buffer

pkg/dwarf/frame/entries.go

@@ -6,7 +6,7 @@ import (
 	"sort"
 )
 
-// Represents a Common Information Entry in
+// CommonInformationEntry represents a Common Information Entry in
 // the Dwarf .debug_frame section.
 type CommonInformationEntry struct {
 	Length                uint32
@@ -20,7 +20,7 @@ type CommonInformationEntry struct {
 	staticBase            uint64
 }
 
-// Represents a Frame Descriptor Entry in the
+// FrameDescriptionEntry represents a Frame Descriptor Entry in the
 // Dwarf .debug_frame section.
 type FrameDescriptionEntry struct {
 	Length       uint32
@@ -30,23 +30,23 @@ type FrameDescriptionEntry struct {
 	order        binary.ByteOrder
 }
 
-// Returns whether or not the given address is within the
+// Cover returns whether or not the given address is within the
 // bounds of this frame.
 func (fde *FrameDescriptionEntry) Cover(addr uint64) bool {
 	return (addr - fde.begin) < fde.size
 }
 
-// Address of first location for this frame.
+// Begin returns address of first location for this frame.
 func (fde *FrameDescriptionEntry) Begin() uint64 {
 	return fde.begin
 }
 
-// Address of last location for this frame.
+// End returns address of last location for this frame.
 func (fde *FrameDescriptionEntry) End() uint64 {
 	return fde.begin + fde.size
 }
 
-// Set up frame for the given PC.
+// EstablishFrame set up frame for the given PC.
 func (fde *FrameDescriptionEntry) EstablishFrame(pc uint64) *FrameContext {
 	return executeDwarfProgramUntilPC(fde, pc)
 }
@@ -57,6 +57,7 @@ func newFrameIndex() FrameDescriptionEntries {
 	return make(FrameDescriptionEntries, 0, 1000)
 }
 
+// ErrNoFDEForPC FDE for PC not found error
 type ErrNoFDEForPC struct {
 	PC uint64
 }
@@ -65,7 +66,7 @@ func (err *ErrNoFDEForPC) Error() string {
 	return fmt.Sprintf("could not find FDE for PC %#v", err.PC)
 }
 
-// Returns the Frame Description Entry for the given PC.
+// FDEForPC returns the Frame Description Entry for the given PC.
 func (fdes FrameDescriptionEntries) FDEForPC(pc uint64) (*FrameDescriptionEntry, error) {
 	idx := sort.Search(len(fdes), func(i int) bool {
 		return fdes[i].Cover(pc) || fdes[i].Begin() >= pc

pkg/dwarf/frame/parser.go

@@ -23,9 +23,9 @@ type parseContext struct {
 	ptrSize int
 }
 
-// Parse takes in data (a byte slice) and returns a slice of
-// commonInformationEntry structures. Each commonInformationEntry
-// has a slice of frameDescriptionEntry structures.
+// Parse takes in data (a byte slice) and returns FrameDescriptionEntries,
+// which is a slice of FrameDescriptionEntry. Each FrameDescriptionEntry
+// has a pointer to CommonInformationEntry.
 func Parse(data []byte, order binary.ByteOrder, staticBase uint64, ptrSize int) FrameDescriptionEntries {
 	var (
 		buf  = bytes.NewBuffer(data)

pkg/dwarf/frame/table.go

@@ -8,6 +8,7 @@ import (
 	"github.com/go-delve/delve/pkg/dwarf/util"
 )
 
+// DWRule wrapper of rule defined for register values.
 type DWRule struct {
 	Rule       Rule
 	Offset     int64
@@ -15,6 +16,7 @@ type DWRule struct {
 	Expression []byte
 }
 
+// FrameContext wrapper of FDE context
 type FrameContext struct {
 	loc           uint64
 	order         binary.ByteOrder
@@ -62,7 +64,7 @@ const (
 	DW_CFA_restore            = (0x3 << 6) // High 2 bits: 0x3, low 6: register
 )
 
-// Rules defined for register values.
+// Rule rule defined for register values.
 type Rule byte
 
 const (
@@ -148,7 +150,7 @@ func (frame *FrameContext) executeDwarfProgram() {
 	}
 }
 
-// Execute dwarf instructions.
+// ExecuteUntilPC execute dwarf instructions.
 func (frame *FrameContext) ExecuteUntilPC(instructions []byte) {
 	frame.buf.Truncate(0)
 	frame.buf.Write(instructions)

pkg/dwarf/line/line_parser.go

@@ -9,6 +9,7 @@ import (
 	"github.com/go-delve/delve/pkg/dwarf/util"
 )
 
+// DebugLinePrologue prologue of .debug_line data.
 type DebugLinePrologue struct {
 	UnitLength     uint32
 	Version        uint16
@@ -22,6 +23,7 @@ type DebugLinePrologue struct {
 	StdOpLengths   []uint8
 }
 
+// DebugLineInfo info of .debug_line data.
 type DebugLineInfo struct {
 	Prologue     *DebugLinePrologue
 	IncludeDirs  []string
@@ -46,6 +48,7 @@ type DebugLineInfo struct {
 	endSeqIsValid      bool
 }
 
+// FileEntry file entry in File Name Table.
 type FileEntry struct {
 	Path        string
 	DirIdx      uint64

pkg/dwarf/line/state_machine.go

@@ -157,7 +157,8 @@ func (lineInfo *DebugLineInfo) AllPCsForFileLines(f string, m map[int][]uint64)
 
 var NoSourceError = errors.New("no source available")
 
-// AllPCsBetween returns all PC addresses between begin and end (including both begin and end) that have the is_stmt flag set and do not belong to excludeFile:excludeLine
+// AllPCsBetween returns all PC addresses between begin and end (including both begin and end)
+// that have the is_stmt flag set and do not belong to excludeFile:excludeLine.
 func (lineInfo *DebugLineInfo) AllPCsBetween(begin, end uint64, excludeFile string, excludeLine int) ([]uint64, error) {
 	if lineInfo == nil {
 		return nil, NoSourceError

pkg/dwarf/util/util.go

@@ -119,6 +119,7 @@ func EncodeSLEB128(out io.ByteWriter, x int64) {
 	}
 }
 
+// ParseString reads a null-terminated string from data.
 func ParseString(data *bytes.Buffer) (string, uint32) {
 	str, err := data.ReadString(0x0)
 	if err != nil {