debug/dwarf: document DWARF class -> Go type mapping

Currently, the only way to know the Go type of an attribute of some
DWARF attribute class was to read the dwarf package code (or
experiment).  This makes it hard to go from the DWARF specification to
writing code that uses the dwarf package.

Fix this by adding a table to the documentation comment of the Field
type that gives the correspondence between DWARF attribute classes and
Go types.

Change-Id: I57c678a551fa1eb46f8207085d5a53d44985e3e7
Reviewed-on: https://go-review.googlesource.com/7280
Reviewed-by: Rob Pike <r@golang.org>
Reviewed-by: Nigel Tao <nigeltao@golang.org>

1 files changed, 19 insertions, 0 deletions

diff --git a/src/debug/dwarf/entry.go b/src/debug/dwarf/entry.go
index 2742ae0eab..5a21da0e9e 100644
--- a/src/debug/dwarf/entry.go
+++ b/src/debug/dwarf/entry.go
@@ -102,6 +102,25 @@ type Entry struct {
 }
 
 // A Field is a single attribute/value pair in an Entry.
+//
+// A value can be one of several "attribute classes" defined by DWARF.
+// The Go types corresponding to each class are:
+//
+//    Class             Go type
+//    -----             -------
+//    address           uint64
+//    block             []byte
+//    constant          int64
+//    flag              bool
+//    reference
+//      to info         dwarf.Offset (for use with Reader.Seek)
+//      to type unit    uint64 (type signature)
+//    string            string
+//    exprloc           []byte
+//    lineptr           int64
+//    loclistptr        int64
+//    macptr            int64
+//    rangelistptr      int64
 type Field struct {
 	Attr Attr
 	Val  interface{}