Add docs

tendermint · Dec 31, 2019 · f906c8a · f906c8a
1 parent 703294c
commit f906c8a
Show file tree

Hide file tree

Showing 4 changed files with 66 additions and 0 deletions.
diff --git a/storeutils/entity_id.go b/storeutils/entity_id.go
@@ -10,23 +10,36 @@ var ZeroEntityID = NewEntityID(0)
 
 type EntityID sdk.Uint
 
+// NewEntityID creates a new EntityID from the specified uint64.
 func NewEntityID(id uint64) EntityID {
 	return EntityID(sdk.NewUint(id))
 }
 
+// NewEntityIDFromString creates a new EntityID from the
+// provided string.
 func NewEntityIDFromString(str string) EntityID {
 	return EntityID(sdk.NewUintFromString(str))
 }
 
+// NewEntityIDFromBytes creates a new EntityID from the
+// provided byte slice. The byte slice must be encoded
+// as big-endian.
 func NewEntityIDFromBytes(b []byte) EntityID {
 	s := new(big.Int).SetBytes(b)
 	return EntityID(sdk.NewUintFromBigInt(s))
 }
 
+// String returns the decimal string
+// representation of this EntityID.
 func (id EntityID) String() string {
 	return sdk.Uint(id).String()
 }
 
+// Bytes returns this EntityID as a
+// fixed-length big-endian byte slice
+// of size 32. The length is fixed in
+// order to facilitate sorting by EntityIDs
+// in the store.
 func (id EntityID) Bytes() []byte {
 	var buf [32]byte
 	bn := sdkUint2Big(sdk.Uint(id))
@@ -35,10 +48,15 @@ func (id EntityID) Bytes() []byte {
 	return buf[:]
 }
 
+// Inc returns a the current EntityID + 1.
+// A new EntityID is returned.
 func (id EntityID) Inc() EntityID {
 	return EntityID(sdk.Uint(id).Add(sdk.OneUint()))
 }
 
+// Dec returns the current EntityID - 1.
+// A new EntityID is returned. If the EntityID
+// is zero, this method is a no-op.
 func (id EntityID) Dec() EntityID {
 	if id.IsZero() {
 		return id
@@ -47,6 +65,9 @@ func (id EntityID) Dec() EntityID {
 	return EntityID(sdk.Uint(id).Sub(sdk.OneUint()))
 }
 
+// Cmp compares two entity IDs.
+// If a > b, 1 is returned. If a < b, -1 is returned.
+// If a == b, 0 is returned.
 func (id EntityID) Cmp(b EntityID) int {
 	uintA := sdk.Uint(id)
 	uintB := sdk.Uint(b)
@@ -62,18 +83,23 @@ func (id EntityID) Cmp(b EntityID) int {
 	return 0
 }
 
+// IsZero returns if this EntityID == 0.
 func (id EntityID) IsZero() bool {
 	return sdk.Uint(id).IsZero()
 }
 
+// Equals returns true if both
+// EntityIDs are equal.
 func (id EntityID) Equals(other EntityID) bool {
 	return sdk.Uint(id).Equal(sdk.Uint(other))
 }
 
+// MarshalAmino marshals this EntityID to Amino.
 func (id EntityID) MarshalAmino() (string, error) {
 	return sdk.Uint(id).MarshalAmino()
 }
 
+// UnmarshalAmino unmarshals this EntityID from Amino.
 func (id *EntityID) UnmarshalAmino(text string) error {
 	var u sdk.Uint
 	err := u.UnmarshalAmino(text)
@@ -85,14 +111,19 @@ func (id *EntityID) UnmarshalAmino(text string) error {
 	return nil
 }
 
+// UnmarshalJSON unmarshals this EntityID from JSON.
 func (id *EntityID) UnmarshalJSON(data []byte) error {
 	return (*sdk.Uint)(id).UnmarshalJSON(data)
 }
 
+// MarshalJSON marshals this EntityID to JSON.
 func (id EntityID) MarshalJSON() ([]byte, error) {
 	return sdk.Uint(id).MarshalJSON()
 }
 
+// Note: this method is a hack, and can be replaced once
+// the new sdk version (> v0.37.4) is released, since it
+// defines a .BigInt() method on sdk.Uint objects.
 func sdkUint2Big(in sdk.Uint) *big.Int {
 	out, _ := new(big.Int).SetString(in.String(), 10)
 	return out

diff --git a/storeutils/get_set.go b/storeutils/get_set.go
@@ -11,6 +11,9 @@ var (
 	ErrAlreadyExists = errors.New("already exists")
 )
 
+// Get unmarshals a binary object in the store
+// identified by sk and key into the object
+// identified by proto.
 func Get(ctx sdk.Context, sk sdk.StoreKey, cdc *codec.Codec, key []byte, proto interface{}) error {
 	store := ctx.KVStore(sk)
 	b := store.Get(key)
@@ -21,11 +24,18 @@ func Get(ctx sdk.Context, sk sdk.StoreKey, cdc *codec.Codec, key []byte, proto i
 	return nil
 }
 
+// Upsert inserts val into the store
+// identified by sk and at the key
+// identified by key.
 func Upsert(ctx sdk.Context, sk sdk.StoreKey, cdc *codec.Codec, key []byte, val interface{}) {
 	store := ctx.KVStore(sk)
 	store.Set(key, cdc.MustMarshalBinaryBare(val))
 }
 
+// Create inserts val into the store
+// identified by sk and at the key
+// identified by key. Create will return
+// an error if the key already exists.
 func Create(ctx sdk.Context, sk sdk.StoreKey, cdc *codec.Codec, key []byte, val interface{}) error {
 	if Has(ctx, sk, key) {
 		return ErrAlreadyExists
@@ -34,6 +44,10 @@ func Create(ctx sdk.Context, sk sdk.StoreKey, cdc *codec.Codec, key []byte, val
 	return nil
 }
 
+// Update inserts val into the store
+// identified by sk and at the key
+// identified by key. Update will return
+// an error if the key does not exist.
 func Update(ctx sdk.Context, sk sdk.StoreKey, cdc *codec.Codec, key []byte, val interface{}) error {
 	if !Has(ctx, sk, key) {
 		return ErrNotFound
@@ -42,6 +56,10 @@ func Update(ctx sdk.Context, sk sdk.StoreKey, cdc *codec.Codec, key []byte, val
 	return nil
 }
 
+// Del deletes the value in the store
+// identified by sk and at the key
+// identified by key. Del will return an error
+// if the key does not exist.
 func Del(ctx sdk.Context, sk sdk.StoreKey, key []byte) error {
 	if !Has(ctx, sk, key) {
 		return ErrNotFound
@@ -51,6 +69,8 @@ func Del(ctx sdk.Context, sk sdk.StoreKey, key []byte) error {
 	return nil
 }
 
+// Has returns true if the specified key
+// exists in the store identified by sk.
 func Has(ctx sdk.Context, sk sdk.StoreKey, key []byte) bool {
 	store := ctx.KVStore(sk)
 	return store.Has(key)

diff --git a/storeutils/keys.go b/storeutils/keys.go
@@ -5,11 +5,16 @@ import (
 	"encoding/binary"
 )
 
+// PrefixKeyString returns a byte slice
+// consisting of the prefix string concatenated
+// with all subkeys.
 func PrefixKeyString(prefix string, subkeys ...[]byte) []byte {
 	buf := [][]byte{[]byte(prefix)}
 	return PrefixKeyBytes(append(buf, subkeys...)...)
 }
 
+// PrefixKeyBytes returns a byte slice consisting
+// of all subkeys concatenated together.
 func PrefixKeyBytes(subkeys ...[]byte) []byte {
 	if len(subkeys) == 0 {
 		return []byte{}
@@ -32,13 +37,19 @@ func PrefixKeyBytes(subkeys ...[]byte) []byte {
 	return buf.Bytes()
 }
 
+// Int64Subkey returns a byte slice
+// from the provided subkey suitable
+// for use as a key in the store.
 func Int64Subkey(subkey int64) []byte {
 	if subkey < 0 {
 		panic("cannot use negative numbers in subkeys")
 	}
 	return Uint64Subkey(uint64(subkey))
 }
 
+// Uint64Subkey returns a byte slice
+// from the provided subkey suitable
+// for use as a key in the store.
 func Uint64Subkey(subkey uint64) []byte {
 	b := make([]byte, 8, 8)
 	binary.BigEndian.PutUint64(b, subkey)

diff --git a/storeutils/seq.go b/storeutils/seq.go
@@ -4,13 +4,17 @@ import (
 	sdk "github.com/cosmos/cosmos-sdk/types"
 )
 
+// IncrementSeq increments the EntityID in the store
+// identified by sk at the key seqKey.
 func IncrementSeq(ctx sdk.Context, sk sdk.StoreKey, seqKey []byte) EntityID {
 	store := ctx.KVStore(sk)
 	seq := GetSeq(ctx, sk, seqKey).Inc()
 	store.Set(seqKey, []byte(seq.String()))
 	return seq
 }
 
+// GetSeq returns the EntityID in the store
+// identified by sk at the key seqKey.
 func GetSeq(ctx sdk.Context, sk sdk.StoreKey, seqKey []byte) EntityID {
 	store := ctx.KVStore(sk)
 	if !store.Has(seqKey) {