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>

diff --git a/src/debug/dwarf/entry.go b/src/debug/dwarf/entry.go
index 2742ae0eabfafbb1e9ad2f7d0ae0a008bb1dda49..5a21da0e9eb42bfd4d419761e0ef42c48c5d57b8 100644 (file)
--- 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{}