docs: add more clear and description comments

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/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"
 )
 
+// BudgetCollection collets all the valid budgets registered in params.Budgets and
+// distributes the total collected coins to collection address.
 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.
 	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/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/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/types/budget.go

@@ -16,6 +16,7 @@ var (
 	reBudgetName       = regexp.MustCompile(fmt.Sprintf(`^%s$`, reBudgetNameString))
 )
 
+// String returns a human-readable string representation of the budget.
 func (budget Budget) String() string {
 	out, _ := budget.MarshalYAML()
 	return out.(string)
@@ -30,28 +31,20 @@ func (budget Budget) MarshalYAML() (interface{}, error) {
 	return string(bz), err
 }
 
+// Validate validates the budget.
 func (budget Budget) Validate() error {
-	//Name only allowed letters(`A-Z, a-z`), digits(`0-9`), and `-` without spaces and the maximum length is 50.
-	err := ValidateName(budget.Name)
-	if err != nil {
+	if err := ValidateName(budget.Name); err != nil {
 		return err
 	}
 
-	// Check that the CollectionAddress is a valid address.
-	_, err = ValidityAddr(budget.CollectionAddress)
-	if err != nil {
-		// TODO: return error with Wrapping
+	if _, err := ValidityAddr(budget.CollectionAddress); err != nil {
 		return err
 	}
 
-	// Check that the BudgetSourceAddress is a valid address.
-	_, err = ValidityAddr(budget.BudgetSourceAddress)
-	if err != nil {
-		// TODO: return error with Wrapping
+	if _, err := ValidityAddr(budget.BudgetSourceAddress); err != nil {
 		return err
 	}
 
-	// EndTime should not be earlier than StartTime.
 	if budget.EndTime.Before(budget.StartTime) {
 		return ErrInvalidStartEndTime
 	}
@@ -62,10 +55,12 @@ func (budget Budget) Validate() error {
 	return nil
 }
 
+// Expired validates the budget's end time expiration.
 func (budget Budget) Expired(blockTime time.Time) bool {
 	return !budget.EndTime.After(blockTime)
 }
 
+// ValidityAddr validates the bech32 address format.
 func ValidityAddr(bech32 string) (sdk.AccAddress, error) {
 	acc, err := sdk.AccAddressFromBech32(bech32)
 	if err != nil {
@@ -75,22 +70,26 @@ func ValidityAddr(bech32 string) (sdk.AccAddress, error) {
 }
 
 // ValidateName is the default validation function for Budget.Name.
+// A budget name only allows alphabet letters(`A-Z, a-z`), digit numbers(`0-9`), and `-`.
+// It doesn't allow spaces and the maximum length is 50 characters.
 func ValidateName(name string) error {
 	if !reBudgetName.MatchString(name) {
 		return sdkerrors.Wrap(ErrInvalidBudgetName, name)
 	}
 	return nil
 }
 
+// BudgetsBySource defines the total rate of budget lists.
 type BudgetsBySource struct {
 	Budgets   []Budget
 	TotalRate sdk.Dec
 }
 
 type BudgetsBySourceMap map[string]BudgetsBySource
 
-// GetBudgetsBySourceMap returns 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.
+// GetBudgetsBySourceMap returns BudgetsBySourceMap that has a list of budgets and their total rate
+// which contain the same BudgetSourceAddress. It can be used to track of what budgets are avilable with BudgetSourceAddress
+// and validate their total rate.
 func GetBudgetsBySourceMap(budgets []Budget) BudgetsBySourceMap {
 	budgetsMap := make(BudgetsBySourceMap)
 	for _, budget := range budgets {

x/budget/types/codec.go

@@ -10,7 +10,7 @@ import (
 func RegisterLegacyAminoCodec(cdc *codec.LegacyAmino) {
 }
 
-// RegisterInterfaces registers the x/budget interfaces types with the interface registry
+// RegisterInterfaces registers the x/budget interfaces types with the interface registry.
 func RegisterInterfaces(registry types.InterfaceRegistry) {
 }