Fix function comments based on best practices from Effective Go

collection.go

@@ -65,7 +65,7 @@ func (t *Collection) closeCollection() { // Just "close" is a keyword.
 	}
 }
 
-// Retrieve an item by its key.  Use withValue of false if you don't
+// GetItem retrieves an item by its key.  Use withValue of false if you don't
 // need the item's value (Item.Val may be nil), which might be able
 // to save on I/O and memory resources, especially for large values.
 // The returned Item should be treated as immutable.
@@ -104,7 +104,7 @@ func (t *Collection) GetItem(key []byte, withValue bool) (i *Item, err error) {
 	}
 }
 
-// Retrieve a value by its key.  Returns nil if the item is not in the
+// Get retrieves a value by its key.  Returns nil if the item is not in the
 // collection.  The returned value should be treated as immutable.
 func (t *Collection) Get(key []byte) (val []byte, err error) {
 	i, err := t.GetItem(key, true)
@@ -117,7 +117,7 @@ func (t *Collection) Get(key []byte) (val []byte, err error) {
 	return nil, nil
 }
 
-// Replace or insert an item of a given key.
+// SetItem replaces or insert an item of a given key.
 // A random item Priority (e.g., rand.Int31()) will usually work well,
 // but advanced users may consider using non-random item priorities
 // at the risk of unbalancing the lookup tree.  The input Item instance
@@ -156,7 +156,7 @@ func (t *Collection) SetItem(item *Item) (err error) {
 	return nil
 }
 
-// Replace or insert an item of a given key.
+// Set replaces or insert an item of a given key.
 func (t *Collection) Set(key []byte, val []byte) error {
 	return t.SetItem(&Item{Key: key, Val: val, Priority: rand.Int31()})
 }
@@ -204,14 +204,14 @@ func (t *Collection) Delete(key []byte) (wasDeleted bool, err error) {
 	return true, nil
 }
 
-// Retrieves the item with the "smallest" key.
+// MinItem retrieves the item with the "smallest" key.
 // The returned item should be treated as immutable.
 func (t *Collection) MinItem(withValue bool) (*Item, error) {
 	return t.store.walk(t, withValue,
 		func(n *node) (*nodeLoc, bool) { return &n.left, true })
 }
 
-// Retrieves the item with the "largest" key.
+// MaxItem retrieves the item with the "largest" key.
 // The returned item should be treated as immutable.
 func (t *Collection) MaxItem(withValue bool) (*Item, error) {
 	return t.store.walk(t, withValue,
@@ -311,7 +311,7 @@ func descendChoice(cmp int, n *node) (bool, *nodeLoc, *nodeLoc) {
 	return cmp > 0, &n.right, &n.left
 }
 
-// Returns total number of items and total key bytes plus value bytes.
+// GetTotals returns total number of items and total key bytes plus value bytes.
 func (t *Collection) GetTotals() (numItems uint64, numBytes uint64, err error) {
 	rnl := t.rootAddRef()
 	defer t.rootDecRef(rnl)
@@ -323,14 +323,14 @@ func (t *Collection) GetTotals() (numItems uint64, numBytes uint64, err error) {
 	return nNode.numNodes, nNode.numBytes, nil
 }
 
-// Returns JSON representation of root node file location.
+// MarshalJSON returns JSON representation of root node file location.
 func (t *Collection) MarshalJSON() ([]byte, error) {
 	rnl := t.rootAddRef()
 	defer t.rootDecRef(rnl)
 	return rnl.MarshalJSON()
 }
 
-// Returns JSON representation of root node file location.
+// MarshalJSON returns JSON representation of root node file location.
 func (rnl *rootNodeLoc) MarshalJSON() ([]byte, error) {
 	loc := rnl.root.Loc()
 	if loc.isEmpty() {
@@ -361,7 +361,7 @@ func (t *Collection) AllocStats() (res AllocStats) {
 	return res
 }
 
-// Writes dirty items of a collection BUT (WARNING) does NOT write new
+// Write writes dirty items of a collection BUT (WARNING) does NOT write new
 // root records.  Use Store.Flush() to write root records, which would
 // make these writes visible to the next file re-opening/re-loading.
 func (t *Collection) Write() error {

store.go

@@ -106,7 +106,7 @@ func NewStoreEx(file StoreFile,
 	return res, nil
 }
 
-// SetCollection() is used to create a named Collection, or to modify
+// SetCollection is used to create a named Collection, or to modify
 // the KeyCompare function on an existing Collection.  In either case,
 // a new Collection to use is returned.  A newly created Collection
 // and any mutations on it won't be persisted until you do a Flush().
@@ -133,7 +133,7 @@ func (s *Store) SetCollection(name string, compare KeyCompare) *Collection {
 	}
 }
 
-// Returns a new, unregistered (non-named) collection.  This allows
+// MakePrivateCollection returns a new, unregistered (non-named) collection.  This allows
 // advanced users to manage collections of private collections.
 func (s *Store) MakePrivateCollection(compare KeyCompare) *Collection {
 	if compare == nil {
@@ -147,7 +147,7 @@ func (s *Store) MakePrivateCollection(compare KeyCompare) *Collection {
 	}
 }
 
-// Retrieves a named Collection.
+// GetCollection retrieves a named Collection.
 func (s *Store) GetCollection(name string) *Collection {
 	coll := *(*map[string]*Collection)(atomic.LoadPointer(&s.coll))
 	return coll[name]
@@ -190,7 +190,7 @@ func copyColl(orig map[string]*Collection) map[string]*Collection {
 	return res
 }
 
-// Writes (appends) any dirty, unpersisted data to file.  As a
+// Flush writes (appends) any dirty, unpersisted data to file.  As a
 // greater-window-of-data-loss versus higher-performance tradeoff,
 // consider having many mutations (Set()'s & Delete()'s) and then
 // have a less occasional Flush() instead of Flush()'ing after every
@@ -251,7 +251,7 @@ func (s *Store) FlushRevert() error {
 	return s.file.Truncate(atomic.LoadInt64(&s.size))
 }
 
-// Returns a read-only snapshot, including any mutations on the
+// Snapshot returns a read-only snapshot, including any mutations on the
 // original Store that have not been Flush()'ed to disk yet.  The
 // snapshot has its mutations and Flush() operations disabled because
 // the original store "owns" writes to the StoreFile.