docs: add more clear and description comments (#53)

* chore: remove unused tx file and update comments

* docs: update comments on proto files

* chore: update comments in types package and handle TODO comments

* fix: broken test

* docs: update comments

* chore: rename BudgetCollection to CollectBudgets and update relevant docs

* refactor: apply suggestion

* docs: make proto-all

Co-authored-by: dongsam <[email protected]>

client/docs/swagger-ui/swagger.yaml

@@ -48,7 +48,7 @@ paths:
                           type: string
                           format: date-time
                           title: end_time specifies the end time of the budget
-                      description: Budget defines the budget struct.
+                      description: Budget defines a budget object.
                     total_collected_coins:
                       type: array
                       items:
@@ -291,10 +291,10 @@ paths:
                     type: integer
                     format: int64
                     title: >-
-                      The universal epoch length in number of blocks, Every
-                      process for budget collecting is executed with this
+                      The universal epoch length in number of blocks
 
-                      epoch_blocks frequency
+                      A collection of budgets is executed with this epoch_blocks
+                      parameter
                   budgets:
                     type: array
                     items:
@@ -326,14 +326,13 @@ paths:
                           type: string
                           format: date-time
                           title: end_time specifies the end time of the budget
-                      description: Budget defines the budget struct.
-                    description: >-
-                      Budgets parameter can be added, deleted, and modified
-                      through gov.ParameterChangeProposal, and for each purpose,
-
-                      the changes in the existing budget list should be applied
-                      and set.
-                description: Params defines the set of params for the budget module.
+                      description: Budget defines a budget object.
+                    title: >-
+                      Budgets parameter can be added, modified, and deleted
+                      through
+
+                      parameter change governance proposal
+                description: Params defines the parameters for the budget module.
             description: >-
               QueryParamsResponse is the response type for the Query/Params RPC
               method.
@@ -568,7 +567,7 @@ definitions:
         type: string
         format: date-time
         title: end_time specifies the end time of the budget
-    description: Budget defines the budget struct.
+    description: Budget defines a budget object.
   cosmos.budget.v1beta1.BudgetResponse:
     type: object
     properties:
@@ -601,7 +600,7 @@ definitions:
             type: string
             format: date-time
             title: end_time specifies the end time of the budget
-        description: Budget defines the budget struct.
+        description: Budget defines a budget object.
       total_collected_coins:
         type: array
         items:
@@ -622,11 +621,9 @@ definitions:
       epoch_blocks:
         type: integer
         format: int64
-        title: >-
-          The universal epoch length in number of blocks, Every process for
-          budget collecting is executed with this
-
-          epoch_blocks frequency
+        title: |-
+          The universal epoch length in number of blocks
+          A collection of budgets is executed with this epoch_blocks parameter
       budgets:
         type: array
         items:
@@ -658,13 +655,11 @@ definitions:
               type: string
               format: date-time
               title: end_time specifies the end time of the budget
-          description: Budget defines the budget struct.
-        description: >-
-          Budgets parameter can be added, deleted, and modified through
-          gov.ParameterChangeProposal, and for each purpose,
-
-          the changes in the existing budget list should be applied and set.
-    description: Params defines the set of params for the budget module.
+          description: Budget defines a budget object.
+        title: |-
+          Budgets parameter can be added, modified, and deleted through
+          parameter change governance proposal
+    description: Params defines the parameters for the budget module.
   cosmos.budget.v1beta1.QueryBudgetsResponse:
     type: object
     properties:
@@ -702,7 +697,7 @@ definitions:
                   type: string
                   format: date-time
                   title: end_time specifies the end time of the budget
-              description: Budget defines the budget struct.
+              description: Budget defines a budget object.
             total_collected_coins:
               type: array
               items:
@@ -733,10 +728,10 @@ definitions:
             type: integer
             format: int64
             title: >-
-              The universal epoch length in number of blocks, Every process for
-              budget collecting is executed with this
+              The universal epoch length in number of blocks
 
-              epoch_blocks frequency
+              A collection of budgets is executed with this epoch_blocks
+              parameter
           budgets:
             type: array
             items:
@@ -768,13 +763,11 @@ definitions:
                   type: string
                   format: date-time
                   title: end_time specifies the end time of the budget
-              description: Budget defines the budget struct.
-            description: >-
-              Budgets parameter can be added, deleted, and modified through
-              gov.ParameterChangeProposal, and for each purpose,
-
-              the changes in the existing budget list should be applied and set.
-        description: Params defines the set of params for the budget module.
+              description: Budget defines a budget object.
+            title: |-
+              Budgets parameter can be added, modified, and deleted through
+              parameter change governance proposal
+        description: Params defines the parameters for the budget module.
     description: QueryParamsResponse is the response type for the Query/Params RPC method.
   google.protobuf.Any:
     type: object

proto/tendermint/budget/v1beta1/budget.proto

@@ -10,19 +10,19 @@ import "cosmos/base/v1beta1/coin.proto";
 
 option go_package = "github.com/tendermint/budget/x/budget/types";
 
-// Params defines the set of params for the budget module.
+// Params defines the parameters for the budget module.
 message Params {
   option (gogoproto.goproto_stringer) = false;
-  // The universal epoch length in number of blocks, Every process for budget collecting is executed with this
-  // epoch_blocks frequency
+  // The universal epoch length in number of blocks
+  // A collection of budgets is executed with this epoch_blocks parameter
   uint32 epoch_blocks = 1 [(gogoproto.moretags) = "yaml:\"epoch_blocks\""];
 
-  // Budgets parameter can be added, deleted, and modified through gov.ParameterChangeProposal, and for each purpose,
-  // the changes in the existing budget list should be applied and set.
+  // Budgets parameter can be added, modified, and deleted through
+  // parameter change governance proposal
   repeated Budget budgets = 2 [(gogoproto.moretags) = "yaml:\"budgets\"", (gogoproto.nullable) = false];
 }
 
-// Budget defines the budget struct.
+// Budget defines a budget object.
 message Budget {
   option (gogoproto.goproto_getters)  = false;
   option (gogoproto.goproto_stringer) = false;
@@ -52,10 +52,11 @@ message Budget {
       [(gogoproto.stdtime) = true, (gogoproto.nullable) = false, (gogoproto.moretags) = "yaml:\"end_time\""];
 }
 
-// The cumulative coins collected in the budget since the bucket was created.
+// TotalCollectedCoins defines total collected coins with relevant metadata.
 message TotalCollectedCoins {
   option (gogoproto.goproto_getters) = false;
 
+  // total_collected_coins specifis the total collected coins in a budget ever since the budget is created
   repeated cosmos.base.v1beta1.Coin total_collected_coins = 1 [
     (gogoproto.moretags)     = "yaml:\"total_collected_coins\"",
     (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins",

proto/tendermint/budget/v1beta1/genesis.proto

@@ -25,12 +25,12 @@ message GenesisState {
       [(gogoproto.nullable) = false, (gogoproto.moretags) = "yaml:\"budget_records\""];
 }
 
-// records the state of each budget after genesis export or import.
+// BudgetRecord records the state of each budget after genesis import or export.
 message BudgetRecord {
-  // the name of the budget
+  // name defines the name of the budget
   string name = 1 [(gogoproto.moretags) = "yaml:\"name\""];
 
-  // the cumulative coins collected in the budget since the bucket was created.
+  // total_collected_coins specifis the total collected coins in a budget ever since the budget is created
   repeated cosmos.base.v1beta1.Coin total_collected_coins = 2 [
     (gogoproto.moretags)     = "yaml:\"total_collected_coins\"",
     (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins",

x/budget/abci.go

@@ -12,10 +12,10 @@ import (
 	"github.com/tendermint/budget/x/budget/types"
 )
 
-// BeginBlocker collect budgets for the current block
+// BeginBlocker collects budgets for the current block
 func BeginBlocker(ctx sdk.Context, req abci.RequestBeginBlock, k keeper.Keeper) {
 	defer telemetry.ModuleMeasureSince(types.ModuleName, time.Now(), telemetry.MetricKeyBeginBlocker)
-	err := k.BudgetCollection(ctx)
+	err := k.CollectBudgets(ctx)
 	if err != nil {
 		panic(err)
 	}

x/budget/client/cli/flags.go

@@ -10,6 +10,7 @@ const (
 	FlagCollectionAddress   = "collection-address"
 )
 
+// flagSetBudgets returns the FlagSet used for budgets.
 func flagSetBudgets() *flag.FlagSet {
 	fs := flag.NewFlagSet("", flag.ContinueOnError)
 

x/budget/client/cli/query.go

@@ -71,6 +71,7 @@ $ %s query %s params
 	return cmd
 }
 
+// GetCmdQueryBudgets implements the query budgets command.
 func GetCmdQueryBudgets() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "budgets",

x/budget/keeper/budget.go

@@ -7,8 +7,9 @@ import (
 	"github.com/tendermint/budget/x/budget/types"
 )
 
-func (k Keeper) BudgetCollection(ctx sdk.Context) error {
-	// Get all the Budgets registered in params.Budgets and select only the valid budgets. If there is no valid budget, exit.
+// CollectBudgets collects all the valid budgets registered in params.Budgets and
+// distributes the total collected coins to collection address.
+func (k Keeper) CollectBudgets(ctx sdk.Context) error {
 	budgets := k.CollectibleBudgets(ctx)
 	if len(budgets) == 0 {
 		return nil
@@ -22,8 +23,9 @@ func (k Keeper) BudgetCollection(ctx sdk.Context) error {
 			outputs = append(outputs, banktypes.NewOutput(to, coins))
 		}
 	}
-	// Create a map by BudgetSourceAddress to handle the budgets for the same BudgetSourceAddress together based on the
-	// same balance when calculating rates for the same BudgetSourceAddress.
+
+	// Get a map GetBudgetsBySourceMap that has a list of budgets and their total rate, which
+	// contain the same BudgetSourceAddress
 	budgetsBySourceMap := types.GetBudgetsBySourceMap(budgets)
 	for budgetSource, budgetsBySource := range budgetsBySourceMap {
 		budgetSourceAcc, err := sdk.AccAddressFromBech32(budgetSource)
@@ -53,6 +55,7 @@ func (k Keeper) BudgetCollection(ctx sdk.Context) error {
 			collectionCoins, changeCoins := budgetSourceBalances.MulDecTruncate(budget.Rate).TruncateDecimal()
 			totalCollectionCoins = totalCollectionCoins.Add(collectionCoins...)
 			totalChangeCoins = totalChangeCoins.Add(changeCoins...)
+
 			// TODO: sendcoins after validation
 			sendCoins(budgetSourceAcc, collectionAcc, collectionCoins)
 			k.AddTotalCollectedCoins(ctx, budget.Name, collectionCoins)

x/budget/keeper/budget_test.go

@@ -6,7 +6,7 @@ import (
 	"github.com/tendermint/budget/x/budget/types"
 )
 
-func (suite *KeeperTestSuite) TestBudgetCollection() {
+func (suite *KeeperTestSuite) TestCollectBudgets() {
 	for _, tc := range []struct {
 		name           string
 		budgets        []types.Budget
@@ -155,7 +155,7 @@ func (suite *KeeperTestSuite) TestBudgetCollection() {
 			params.EpochBlocks = tc.epochBlocks
 			suite.keeper.SetParams(suite.ctx, params)
 
-			err := suite.keeper.BudgetCollection(suite.ctx)
+			err := suite.keeper.CollectBudgets(suite.ctx)
 			if tc.expectErr {
 				suite.Error(err)
 			} else {
@@ -211,7 +211,7 @@ func (suite *KeeperTestSuite) TestTotalCollectedCoins() {
 	suite.Require().Equal(sdk.Coins(nil), collectedCoins)
 
 	suite.ctx = suite.ctx.WithBlockTime(mustParseRFC3339("2021-08-31T00:00:00Z"))
-	err := suite.keeper.BudgetCollection(suite.ctx)
+	err := suite.keeper.CollectBudgets(suite.ctx)
 	suite.Require().NoError(err)
 
 	collectedCoins = suite.keeper.GetTotalCollectedCoins(suite.ctx, "budget1")

x/budget/keeper/genesis_test.go

@@ -16,7 +16,7 @@ func (suite *KeeperTestSuite) TestInitGenesis() {
 	suite.Require().Equal(emptyGenState, suite.keeper.ExportGenesis(suite.ctx))
 	suite.Require().Nil(emptyGenState.BudgetRecords)
 
-	err := suite.keeper.BudgetCollection(suite.ctx)
+	err := suite.keeper.CollectBudgets(suite.ctx)
 	suite.Require().NoError(err)
 	var genState *types.GenesisState
 	suite.Require().NotPanics(func() {

x/budget/keeper/grpc_query.go

@@ -18,13 +18,15 @@ type Querier struct {
 
 var _ types.QueryServer = Querier{}
 
+// Params queries the parameters of the budget module.
 func (k Querier) Params(c context.Context, _ *types.QueryParamsRequest) (*types.QueryParamsResponse, error) {
 	ctx := sdk.UnwrapSDKContext(c)
 	var params types.Params
 	k.paramSpace.GetParamSet(ctx, &params)
 	return &types.QueryParamsResponse{Params: params}, nil
 }
 
+// Budgets queries all budgets.
 func (k Querier) Budgets(c context.Context, req *types.QueryBudgetsRequest) (*types.QueryBudgetsResponse, error) {
 	if req == nil {
 		return nil, status.Error(codes.InvalidArgument, "invalid request")

x/budget/keeper/grpc_query_test.go

@@ -58,7 +58,7 @@ func (suite *KeeperTestSuite) TestGRPCBudgets() {
 	expectedCoins, _ := sdk.NewDecCoinsFromCoins(balance...).MulDec(sdk.NewDecWithPrec(5, 2)).TruncateDecimal()
 
 	suite.ctx = suite.ctx.WithBlockTime(mustParseRFC3339("2021-08-31T00:00:00Z"))
-	err := suite.keeper.BudgetCollection(suite.ctx)
+	err := suite.keeper.CollectBudgets(suite.ctx)
 	suite.Require().NoError(err)
 
 	for _, tc := range []struct {

x/budget/module.go

@@ -72,10 +72,9 @@ func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx sdkclient.Context, mux
 }
 
 // GetTxCmd returns the root tx command for the budget module.
+// Modifying parameters of a budget can be done through governance process, not through transaction level.
 func (AppModuleBasic) GetTxCmd() *cobra.Command {
-	// Modification of Budgets of Params proceeds to governance proposition, not to Tx.
 	return nil
-
 }
 
 // GetQueryCmd returns the root query command for the budget module.

x/budget/spec/03_state_transitions.md

@@ -4,14 +4,14 @@
 
 This document describes the state transaction operations pertaining to the budget module.
 
-- BudgetCollection
+- CollectBudgets
 - TotalCollectedCoins
-## BudgetCollection
+## CollectBudgets
 
 Get all budgets registered in `params.Budgets` and select the valid budgets to collect budgets for the block by its respective plan.
 This state transition occurs at each `BeginBlock`. You can read more about it in [04_begin_block.md](04_begin_block.md).
 
 ## TotalCollectedCoins
 
 `TotalCollectedCoins` are accumulated coins in a budget since the creation of the budget.
-This state transition occurs at each `BeginBlock` with `BudgetCollection`. You can read more about it in [04_begin_block.md](04_begin_block.md).
+This state transition occurs at each `BeginBlock` with `CollectBudgets`. You can read more about it in [04_begin_block.md](04_begin_block.md).