chore: add comments for types

tendermint · Oct 12, 2021 · 5ffc807 · 5ffc807
1 parent e8c39f1
commit 5ffc807
Show file tree

Hide file tree

Showing 5 changed files with 46 additions and 2 deletions.
diff --git a/x/farming/types/expected_keepers.go b/x/farming/types/expected_keepers.go
@@ -9,7 +9,6 @@ import (
 type BankKeeper interface {
 	SendCoins(ctx sdk.Context, fromAddr sdk.AccAddress, toAddr sdk.AccAddress, amt sdk.Coins) error
 	GetAllBalances(ctx sdk.Context, addr sdk.AccAddress) sdk.Coins
-	//GetBalance(ctx sdk.Context, addr sdk.AccAddress, denom string) sdk.Coin
 	SpendableCoins(ctx sdk.Context, addr sdk.AccAddress) sdk.Coins
 
 	SendCoinsFromModuleToAccount(ctx sdk.Context, senderModule string, recipientAddr sdk.AccAddress, amt sdk.Coins) error

diff --git a/x/farming/types/genesis.go b/x/farming/types/genesis.go
@@ -115,6 +115,7 @@ func ValidateGenesis(data GenesisState) error {
 	return nil
 }
 
+// Validate validates PlanRecord.
 func (record PlanRecord) Validate() error {
 	plan, err := UnpackPlan(&record.Plan)
 	if err != nil {
@@ -129,6 +130,7 @@ func (record PlanRecord) Validate() error {
 	return nil
 }
 
+// Validate validates StakingRecord.
 func (record StakingRecord) Validate() error {
 	if _, err := sdk.AccAddressFromBech32(record.Farmer); err != nil {
 		return err
@@ -142,6 +144,7 @@ func (record StakingRecord) Validate() error {
 	return nil
 }
 
+// Validate validates QueuedStakingRecord.
 func (record QueuedStakingRecord) Validate() error {
 	if _, err := sdk.AccAddressFromBech32(record.Farmer); err != nil {
 		return err
@@ -155,6 +158,7 @@ func (record QueuedStakingRecord) Validate() error {
 	return nil
 }
 
+// Validate validates HistoricalRewardsRecord.
 func (record HistoricalRewardsRecord) Validate() error {
 	if err := sdk.ValidateDenom(record.StakingCoinDenom); err != nil {
 		return err
@@ -165,6 +169,7 @@ func (record HistoricalRewardsRecord) Validate() error {
 	return nil
 }
 
+// Validate validates OutstandingRewardsRecord.
 func (record OutstandingRewardsRecord) Validate() error {
 	if err := sdk.ValidateDenom(record.StakingCoinDenom); err != nil {
 		return err
@@ -175,6 +180,7 @@ func (record OutstandingRewardsRecord) Validate() error {
 	return nil
 }
 
+// Validate validates CurrentEpochRecord.
 func (record CurrentEpochRecord) Validate() error {
 	if err := sdk.ValidateDenom(record.StakingCoinDenom); err != nil {
 		return err

diff --git a/x/farming/types/keys.go b/x/farming/types/keys.go
@@ -50,42 +50,54 @@ func GetStakingKey(stakingCoinDenom string, farmerAcc sdk.AccAddress) []byte {
 	return append(append(StakingKeyPrefix, LengthPrefixString(stakingCoinDenom)...), farmerAcc...)
 }
 
+// GetStakingIndexKey returns an indexing key for a staking.
 func GetStakingIndexKey(farmerAcc sdk.AccAddress, stakingCoinDenom string) []byte {
 	return append(append(StakingIndexKeyPrefix, address.MustLengthPrefix(farmerAcc)...), []byte(stakingCoinDenom)...)
 }
 
+// GetStakingsByFarmerPrefix returns a key prefix used to iterate
+// stakings by a farmer.
 func GetStakingsByFarmerPrefix(farmerAcc sdk.AccAddress) []byte {
 	return append(StakingIndexKeyPrefix, address.MustLengthPrefix(farmerAcc)...)
 }
 
+// GetQueuedStakingKey returns a key for a queued staking.
 func GetQueuedStakingKey(stakingCoinDenom string, farmerAcc sdk.AccAddress) []byte {
 	return append(append(QueuedStakingKeyPrefix, LengthPrefixString(stakingCoinDenom)...), farmerAcc...)
 }
 
+// GetQueuedStakingIndexKey returns an indexing key for a queuded staking.
 func GetQueuedStakingIndexKey(farmerAcc sdk.AccAddress, stakingCoinDenom string) []byte {
 	return append(append(QueuedStakingIndexKeyPrefix, address.MustLengthPrefix(farmerAcc)...), []byte(stakingCoinDenom)...)
 }
 
+// GetQueuedStakingByFarmerPrefix returns a key prefix used to iterate
+// queued stakings by a farmer.
 func GetQueuedStakingByFarmerPrefix(farmerAcc sdk.AccAddress) []byte {
 	return append(QueuedStakingIndexKeyPrefix, address.MustLengthPrefix(farmerAcc)...)
 }
 
+// GetTotalStakingsKey returns a key for a total stakings info.
 func GetTotalStakingsKey(stakingCoinDenom string) []byte {
 	return append(TotalStakingKeyPrefix, []byte(stakingCoinDenom)...)
 }
 
+// GetHistoricalRewardsKey returns a key for a historical rewards record.
 func GetHistoricalRewardsKey(stakingCoinDenom string, epoch uint64) []byte {
 	return append(append(HistoricalRewardsKeyPrefix, LengthPrefixString(stakingCoinDenom)...), sdk.Uint64ToBigEndian(epoch)...)
 }
 
+// GetCurrentEpochKey returns a key for a current epoch info.
 func GetCurrentEpochKey(stakingCoinDenom string) []byte {
 	return append(CurrentEpochKeyPrefix, []byte(stakingCoinDenom)...)
 }
 
+// GetOutstandingRewardsKey returns a key for an outstanding rewards record.
 func GetOutstandingRewardsKey(stakingCoinDenom string) []byte {
 	return append(OutstandingRewardsKeyPrefix, []byte(stakingCoinDenom)...)
 }
 
+// ParseStakingKey parses a staking key.
 func ParseStakingKey(key []byte) (stakingCoinDenom string, farmerAcc sdk.AccAddress) {
 	if !bytes.HasPrefix(key, StakingKeyPrefix) {
 		panic("key does not have proper prefix")
@@ -96,6 +108,7 @@ func ParseStakingKey(key []byte) (stakingCoinDenom string, farmerAcc sdk.AccAddr
 	return
 }
 
+// ParseStakingIndexKey parses a staking index key.
 func ParseStakingIndexKey(key []byte) (farmerAcc sdk.AccAddress, stakingCoinDenom string) {
 	if !bytes.HasPrefix(key, StakingIndexKeyPrefix) {
 		panic("key does not have proper prefix")
@@ -106,6 +119,7 @@ func ParseStakingIndexKey(key []byte) (farmerAcc sdk.AccAddress, stakingCoinDeno
 	return
 }
 
+// ParseQueuedStakingKey parses a queued staking key.
 func ParseQueuedStakingKey(key []byte) (stakingCoinDenom string, farmerAcc sdk.AccAddress) {
 	if !bytes.HasPrefix(key, QueuedStakingKeyPrefix) {
 		panic("key does not have proper prefix")
@@ -116,6 +130,7 @@ func ParseQueuedStakingKey(key []byte) (stakingCoinDenom string, farmerAcc sdk.A
 	return
 }
 
+// ParseQueuedStakingIndexKey parses a queued staking index key.
 func ParseQueuedStakingIndexKey(key []byte) (farmerAcc sdk.AccAddress, stakingCoinDenom string) {
 	if !bytes.HasPrefix(key, QueuedStakingIndexKeyPrefix) {
 		panic("key does not have proper prefix")
@@ -126,6 +141,7 @@ func ParseQueuedStakingIndexKey(key []byte) (farmerAcc sdk.AccAddress, stakingCo
 	return
 }
 
+// ParseHistoricalRewardsKey parses a historical rewards key.
 func ParseHistoricalRewardsKey(key []byte) (stakingCoinDenom string, epoch uint64) {
 	if !bytes.HasPrefix(key, HistoricalRewardsKeyPrefix) {
 		panic("key does not have proper prefix")
@@ -136,6 +152,7 @@ func ParseHistoricalRewardsKey(key []byte) (stakingCoinDenom string, epoch uint6
 	return
 }
 
+// ParseCurrentEpochKey parses a current epoch key.
 func ParseCurrentEpochKey(key []byte) (stakingCoinDenom string) {
 	if !bytes.HasPrefix(key, CurrentEpochKeyPrefix) {
 		panic("key does not have proper prefix")
@@ -144,6 +161,7 @@ func ParseCurrentEpochKey(key []byte) (stakingCoinDenom string) {
 	return
 }
 
+// ParseOutstandingRewardsKey parses an outstanding rewards key.
 func ParseOutstandingRewardsKey(key []byte) (stakingCoinDenom string) {
 	if !bytes.HasPrefix(key, OutstandingRewardsKeyPrefix) {
 		panic("key does not have proper prefix")
@@ -152,7 +170,8 @@ func ParseOutstandingRewardsKey(key []byte) (stakingCoinDenom string) {
 	return
 }
 
-// LengthPrefixString is LengthPrefix for string.
+// LengthPrefixString returns length-prefixed bytes representation
+// of a string.
 func LengthPrefixString(s string) []byte {
 	bz := []byte(s)
 	bzLen := len(bz)

diff --git a/x/farming/types/plan.go b/x/farming/types/plan.go
@@ -210,20 +210,23 @@ func (plan BasePlan) MarshalYAML() (interface{}, error) {
 	return string(bz), err
 }
 
+// NewFixedAmountPlan returns a new fixed amount plan.
 func NewFixedAmountPlan(basePlan *BasePlan, epochAmount sdk.Coins) *FixedAmountPlan {
 	return &FixedAmountPlan{
 		BasePlan:    basePlan,
 		EpochAmount: epochAmount,
 	}
 }
 
+// NewRatioPlan returns a new ratio plan.
 func NewRatioPlan(basePlan *BasePlan, epochRatio sdk.Dec) *RatioPlan {
 	return &RatioPlan{
 		BasePlan:   basePlan,
 		EpochRatio: epochRatio,
 	}
 }
 
+// PlanI represents a farming plan.
 type PlanI interface {
 	proto.Message
 
@@ -362,6 +365,8 @@ func IsPlanActiveAt(plan PlanI, t time.Time) bool {
 	return !plan.GetStartTime().After(t) && plan.GetEndTime().After(t)
 }
 
+// PrivatePlanFarmingPoolAddress returns a unique farming pool address
+// for a newly created plan.
 func PrivatePlanFarmingPoolAddress(name string, planId uint64) sdk.AccAddress {
 	poolAddrName := strings.Join([]string{PrivatePlanFarmingPoolAddrPrefix, fmt.Sprint(planId), name}, PoolAddrSplitter)
 	return address.Module(ModuleName, []byte(poolAddrName))

diff --git a/x/farming/types/proposal.go b/x/farming/types/proposal.go
@@ -104,14 +104,21 @@ func NewAddRequestProposal(
 	}
 }
 
+// IsForFixedAmountPlan returns true if the request is for
+// fixed amount plan.
+// It checks if EpochAmount is not zero.
 func (p *AddRequestProposal) IsForFixedAmountPlan() bool {
 	return !p.EpochAmount.IsZero()
 }
 
+// IsForRatioPlan returns true if the request is for
+// ratio plan.
+// It checks if EpochRatio is not zero.
 func (p *AddRequestProposal) IsForRatioPlan() bool {
 	return !p.EpochRatio.IsNil() && !p.EpochRatio.IsZero()
 }
 
+// Validate validates AddRequestProposal.
 func (p *AddRequestProposal) Validate() error {
 	if len(p.Name) > MaxNameLength {
 		return sdkerrors.Wrapf(ErrInvalidPlanNameLength, "plan name cannot be longer than max length of %d", MaxNameLength)
@@ -165,14 +172,21 @@ func NewUpdateRequestProposal(
 	}
 }
 
+// IsForFixedAmountPlan returns true if the request is for
+// fixed amount plan.
+// It checks if EpochAmount is not zero.
 func (p *UpdateRequestProposal) IsForFixedAmountPlan() bool {
 	return !p.EpochAmount.IsZero()
 }
 
+// IsForRatioPlan returns true if the request is for
+// ratio plan.
+// It checks if EpochRatio is not zero.
 func (p *UpdateRequestProposal) IsForRatioPlan() bool {
 	return !p.EpochRatio.IsNil() && !p.EpochRatio.IsZero()
 }
 
+// Validate validates UpdateRequestProposal.
 func (p *UpdateRequestProposal) Validate() error {
 	if p.PlanId == 0 {
 		return sdkerrors.Wrapf(sdkerrors.ErrInvalidRequest, "invalid plan id: %d", p.PlanId)
@@ -213,6 +227,7 @@ func NewDeleteRequestProposal(id uint64) *DeleteRequestProposal {
 	}
 }
 
+// Validate validates DeleteRequestProposal.
 func (p *DeleteRequestProposal) Validate() error {
 	if p.PlanId == 0 {
 		return sdkerrors.Wrapf(sdkerrors.ErrInvalidRequest, "invalid plan id: %d", p.PlanId)