Ensure all exported functions and types have descriptive comments

obj/dump.go

@@ -8,6 +8,7 @@ import (
 	"sort"
 )
 
+// NewDump returns a *Dump instance populated with the specified file path.
 func NewDump(filePath string) *Dump {
 	return &Dump{FilePath: filePath}
 }
@@ -54,6 +55,8 @@ func (s *Dump) Process() error {
 	return nil
 }
 
+// PrintEntryAddress prints the memory addresses in hex (0x...) format of the
+// entries for the list of given indexes.
 func (s *Dump) PrintEntryAddress(indexes []*string) {
 	for _, index := range indexes {
 		if entry, ok := s.Entries[*index]; ok {
@@ -62,6 +65,9 @@ func (s *Dump) PrintEntryAddress(indexes []*string) {
 	}
 }
 
+// PrintEntryJSON prints the full JSON blob from the input file for the entries
+// with the given indexes. It does this by using the Offset value of the entries
+// to avoid having to load up the whole dump file in memory.
 func (s *Dump) PrintEntryJSON(indexes []*string) error {
 	file, err := os.Open(s.FilePath)
 	defer file.Close()

obj/entry.go

@@ -1,5 +1,7 @@
 package obj
 
+// NewEntry returns a new *Entry instance initialized with a *Object of the
+// given input JSON data.
 func NewEntry(inputJSON []byte) (*Entry, error) {
 	obj, err := NewObject(inputJSON)
 	if err != nil {
@@ -19,6 +21,7 @@ type Entry struct {
 	Index  string
 }
 
+// Address returns the Address property of the entry's Object.
 func (s *Entry) Address() string {
 	return s.Object.Address
 }

obj/object.go

@@ -4,6 +4,8 @@ import "encoding/json"
 
 //go:generate easyjson -all object.go
 
+// NewObject returns a new *Object instance with it's attributes populated from
+// the given input JSON data.
 func NewObject(inputJSON []byte) (*Object, error) {
 	var obj Object
 	err := json.Unmarshal(inputJSON, &obj)
@@ -11,11 +13,14 @@ func NewObject(inputJSON []byte) (*Object, error) {
 	return &obj, err
 }
 
+// Object is a minimal representation of a Ruby heap object as exported from
+// Ruby via `ObjectSpace.dump_all`.
 type Object struct {
 	Address string `json:"address"`
 	Type    string `json:"type"`
 }
 
+// Index returns a unique index for the given Object.
 func (s *Object) Index() string {
 	return s.Address + ":" + s.Type
 }