Cherry-pick Suggestions for Swagger documentation QA (2.2.1)

proto/tendermint/liquidity/v1beta1/genesis.proto

@@ -6,7 +6,7 @@ import "gogoproto/gogo.proto";
 
 option go_package = "github.com/tendermint/liquidity/x/liquidity/types";
 
-// record of the state of each pool for variable checking when genesis export or import
+// record of the state of each pool after genesis export or import, used to check variables
 message PoolRecord {
     Pool pool = 1 [(gogoproto.nullable) = false, (gogoproto.moretags) = "yaml:\"pool\""];
     PoolMetadata pool_metadata = 2 [(gogoproto.nullable) = false, (gogoproto.moretags) = "yaml:\"pool_metadata\""];

proto/tendermint/liquidity/v1beta1/liquidity.proto

@@ -13,8 +13,8 @@ option (gogoproto.goproto_getters_all) = false;
 message PoolType {
     option (gogoproto.equal) = true;
 
-    // This is the id of the pool_type that will be used as pool_type_id for pool creation.
-    // In this version, pool-type-id 1 is only available
+    // The id of the pool_type to use as pool_type_id for pool creation.
+    // Only pool-type-id 1 is supported
     // {"id":1,"name":"ConstantProductLiquidityPool","min_reserve_coin_num":2,"max_reserve_coin_num":2,"description":""}
     uint32 id = 1 [(gogoproto.moretags) = "yaml:\"id\"",
         (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
@@ -87,7 +87,7 @@ message Params {
             format: "sdk.Int"
         }];
 
-    // Fee paid for new Liquidity Pool creation to prevent spamming
+    // Fee to create a Liquidity Pool. 
     repeated cosmos.base.v1beta1.Coin pool_creation_fee = 5 [
         (gogoproto.moretags)   = "yaml:\"pool_creation_fee\"",
         (gogoproto.nullable)   = false,
@@ -135,19 +135,9 @@ message Params {
             example: "\"1\"",
             format: "uint32"
         }];
-
-    //    // fees paid for each batch messages, to be added v2
-    //    repeated cosmos.base.v1beta1.Coin liquidity_msg_fee = 5 [
-    //        (gogoproto.moretags)   = "yaml:\"liquidity_msg_fee\"",
-    //        (gogoproto.nullable)   = false,
-    //        (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins",
-    //        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    //            example: "[{\"denom\": \"uatom\", \"amount\": \"50000\"}]",
-    //            format: "sdk.Coins"
-    //        }];
 }
 
-// Pool defines the liquidity pool that contains pool information
+// The liquidity pool information
 message Pool {
     option (gogoproto.equal) = true;
     option (gogoproto.goproto_stringer) = true;
@@ -186,7 +176,7 @@ message Pool {
         }];
 }
 
-// Metadata of the state of each pool for invariant checking when genesis export or import
+// Metadata for the state of each pool for invariant checking after genesis export or import
 message PoolMetadata {
     option (gogoproto.equal) = true;
     option (gogoproto.goproto_stringer) = true;
@@ -218,7 +208,7 @@ message PoolMetadata {
         }];
 }
 
-// PoolBatch defines the batch(es) of a given liquidity pool that contains indexes of deposit / withdraw / swap messages. Index param increments by 1 if the pool id is same.
+// The batch or batches of a given liquidity pool that contains indexes of the deposit, withdraw, and swap messages. The index param increments by 1 if the pool id exists.
 message PoolBatch {
     option (gogoproto.equal) = true;
     option (gogoproto.goproto_stringer) = true;
@@ -272,7 +262,7 @@ message PoolBatch {
         }];
 }
 
-// DepositMsgState defines the state of deposit message that contains state information as it is processed in the next batch(s)
+// DepositMsgState defines the state of the deposit message that contains the state information as it is processed in the next batch or batches
 message DepositMsgState {
 
     // height where this message is appended to the batch
@@ -311,7 +301,7 @@ message DepositMsgState {
     MsgDepositWithinBatch msg = 6 [(gogoproto.moretags) = "yaml:\"msg\""];
 }
 
-// WithdrawMsgState defines the state of withdraw message that contains state information as it is processed in the next batch(s)
+// WithdrawMsgState defines the state of the withdraw message that contains state information as it is processed in the next batch or batches 
 message WithdrawMsgState {
 
     // height where this message is appended to the batch
@@ -350,7 +340,7 @@ message WithdrawMsgState {
     MsgWithdrawWithinBatch msg = 6 [(gogoproto.moretags) = "yaml:\"msg\""];
 }
 
-// SwapMsgState defines the state of swap message that contains state information as it is processed in the next batch(s)
+// SwapMsgState defines the state of swap message that contains state information as it is processed in the next batch or batches
 message SwapMsgState {
 
     // height where this message is appended to the batch

proto/tendermint/liquidity/v1beta1/tx.proto

@@ -16,14 +16,14 @@ service Msg {
   // Submit deposit to the liquidity pool batch.
   rpc DepositWithinBatch(MsgDepositWithinBatch) returns (MsgDepositWithinBatchResponse);
 
-  // Submit withdraw from to the liquidity pool batch.
+  // Submit withdraw from the liquidity pool batch.
   rpc WithdrawWithinBatch(MsgWithdrawWithinBatch) returns (MsgWithdrawWithinBatchResponse);
 
   // Submit swap to the liquidity pool batch.
   rpc Swap(MsgSwapWithinBatch) returns (MsgSwapWithinBatchResponse);
 }
 
-// MsgCreatePool defines an sdk.Msg type that supports submitting create liquidity pool
+// MsgCreatePool defines an sdk.Msg type that creates a liquidity pool
 //
 // See: https://github.com/tendermint/liquidity/blob/develop/x/liquidity/spec/04_messages.md
 message MsgCreatePool {
@@ -37,14 +37,14 @@ message MsgCreatePool {
       format: "sdk.AccAddress"
     }];
 
-  // id of target pool type, only 1 is allowed on this version, Must match the value in the pool.
+  // id of the target pool type. Must match the value in the pool. 
   uint32 pool_type_id = 2 [(gogoproto.moretags) = "yaml:\"pool_type_id\"",
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"1\"",
       format: "uint32"
   }];
 
-  // reserve coin pair of the pool to deposit
+  // reserve coin pair to deposit to the pool
   repeated cosmos.base.v1beta1.Coin deposit_coins = 4 [(gogoproto.nullable) = false,
     (gogoproto.moretags) = "yaml:\"deposit_coins\"",
     (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins",
@@ -57,10 +57,10 @@ message MsgCreatePool {
 // MsgCreatePoolResponse defines the Msg/CreatePool response type.
 message MsgCreatePoolResponse {}
 
-// `MsgDepositWithinBatch defines` an `sdk.Msg` type that supports submitting deposit request to the batch of the liquidity pool
-// Deposit submit to the batch of the Liquidity pool with the specified `pool_id`, `deposit_coins` for reserve
-// this requests are stacked in the batch of the liquidity pool, not immediately processed and
-// processed in the `endblock` at once with other requests.
+// `MsgDepositWithinBatch defines` an `sdk.Msg` type that supports submitting a deposit request to the batch of the liquidity pool
+// The deposit is submitted with the specified `pool_id` and reserve `deposit_coins`
+// The deposit requests are stacked in the liquidity pool batch and are not immediately processed
+// Batch deposit requests are processed in the `endblock` at the same time as other requests.
 //
 // See: https://github.com/tendermint/liquidity/blob/develop/x/liquidity/spec/04_messages.md
 message MsgDepositWithinBatch {
@@ -96,7 +96,7 @@ message MsgDepositWithinBatch {
 // MsgDepositWithinBatchResponse defines the Msg/DepositWithinBatch response type.
 message MsgDepositWithinBatchResponse {}
 
-// `MsgWithdrawWithinBatch` defines an `sdk.Msg` type that supports submitting withdraw request to the batch of the liquidity pool
+// `MsgWithdrawWithinBatch` defines an `sdk.Msg` type that submits a withdraw request to the liquidity pool batch
 // Withdraw submit to the batch from the Liquidity pool with the specified `pool_id`, `pool_coin` of the pool
 // this requests are stacked in the batch of the liquidity pool, not immediately processed and
 // processed in the `endblock` at once with other requests.
@@ -130,15 +130,14 @@ message MsgWithdrawWithinBatch {
 // MsgWithdrawWithinBatchResponse defines the Msg/WithdrawWithinBatch response type.
 message MsgWithdrawWithinBatchResponse {}
 
-// `MsgSwapWithinBatch` defines an sdk.Msg type that supports submitting swap offer request to the batch of the liquidity pool
-// Swap offer submit to the batch to the Liquidity pool with the specified the `pool_id`, `swap_type_id`,
+// `MsgSwapWithinBatch` defines an sdk.Msg type that submits a swap offer request to the liquidity pool batch
+// The swap offer is submitted with the specified the `pool_id`, `swap_type_id`,
 // `demand_coin_denom` with the coin and the price you're offering
-// and `offer_coin_fee` must half of offer coin amount * current `params.swap_fee_rate` for reservation to pay fees
-// this requests are stacked in the batch of the liquidity pool, not immediately processed and
-// processed in the `endblock` at once with other requests
-// You should request the same each field as the pool
-// Currently, only the default `swap_type_id`1 is available on this version
-// The detailed swap algorithm can be found here.
+// The `offer_coin_fee` must be half of offer coin amount * current `params.swap_fee_rate` to qualify for a reservation to pay fees
+// This request is added to the pool and executed at the end of the batch (`endblock`)
+// You must submit the request using the same fields as the pool
+// Only the default `swap_type_id`1 is supported
+// The detailed swap algorithm is shown here.
 //
 // See: https://github.com/tendermint/liquidity/tree/develop/doc
 // https://github.com/tendermint/liquidity/blob/develop/x/liquidity/spec/04_messages.md
@@ -159,14 +158,14 @@ message MsgSwapWithinBatch {
       format: "uint64"
     }];
 
-  // id of swap type, only 1 is allowed on this version, Must match the value in the pool.
+  // id of swap type. Must match the value in the pool.
   uint32 swap_type_id = 3 [(gogoproto.moretags) = "yaml:\"swap_type_id\"",
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"1\"",
       format: "uint32"
     }];
 
-  // offer sdk.coin for the swap request, Must match the denom in the pool.
+  // offer sdk.coin for the swap request, must match the denom in the pool.
   cosmos.base.v1beta1.Coin offer_coin = 4 [
     (gogoproto.nullable)     = false,
     (gogoproto.moretags)     = "yaml:\"offer_coin\"",
@@ -175,7 +174,7 @@ message MsgSwapWithinBatch {
       format: "sdk.Coin"
     }];
 
-  // denom of demand coin to be exchanged on the swap request, Must match the denom in the pool.
+  // denom of demand coin to be exchanged on the swap request, must match the denom in the pool.
   string demand_coin_denom = 5 [(gogoproto.moretags) = "yaml:\"demand_coin_denom\"",
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"denomB\"",
@@ -204,4 +203,4 @@ message MsgSwapWithinBatch {
 }
 
 // MsgSwapWithinBatchResponse defines the Msg/Swap response type.
-message MsgSwapWithinBatchResponse {}
+message MsgSwapWithinBatchResponse {}