Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: Add "Since:" on proto doc comments #10434

Merged
merged 7 commits into from
Oct 27, 2021
Merged

chore: Add "Since:" on proto doc comments #10434

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
cb3ea4a
chore: Add `@since` on proto doc comments
amaury1093 Oct 25, 2021
be44209
make proto gen
amaury1093 Oct 25, 2021
390a416
Remove v
amaury1093 Oct 25, 2021
1c8a923
Use `Since: cosmos-sdk 0.43`
amaury1093 Oct 26, 2021
f74fd81
Add everywhere else and make-proto-gen
amaury1093 Oct 26, 2021
42d543e
Merge branch 'master' into am/protobuf-since
amaury1093 Oct 26, 2021
83a30b8
Merge branch 'master' into am/protobuf-since
amaury1093 Oct 27, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 9 additions & 8 deletions client/grpc/tmservice/query.pb.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

22 changes: 18 additions & 4 deletions docs/core/proto-docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -855,7 +855,9 @@ pagination. Ex:
| `offset` | [uint64](#uint64) | | offset is a numeric offset that can be used when key is unavailable. It is less efficient than using key. Only one of offset or key should be set. |
| `limit` | [uint64](#uint64) | | limit is the total number of results to be returned in the result page. If left empty it will default to a value to be set by each app. |
| `count_total` | [bool](#bool) | | count_total is set to true to indicate that the result set should include a count of the total number of items available for pagination in UIs. count_total is only respected when offset is used. It is ignored when key is set. |
| `reverse` | [bool](#bool) | | reverse is set to true if results are to be returned in the descending order. |
| `reverse` | [bool](#bool) | | reverse is set to true if results are to be returned in the descending order.

@since Cosmos SDK 0.43 |



Expand Down Expand Up @@ -1020,6 +1022,8 @@ QueryAccountResponse is the response type for the Query/Account RPC method.
### QueryAccountsRequest
QueryAccountsRequest is the request type for the Query/Accounts RPC method.

@since Cosmos SDK 0.43


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
Expand All @@ -1035,6 +1039,8 @@ QueryAccountsRequest is the request type for the Query/Accounts RPC method.
### QueryAccountsResponse
QueryAccountsResponse is the response type for the Query/Accounts RPC method.

@since Cosmos SDK 0.43


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
Expand Down Expand Up @@ -1109,7 +1115,9 @@ Query defines the gRPC querier service.

| Method Name | Request Type | Response Type | Description | HTTP Verb | Endpoint |
| ----------- | ------------ | ------------- | ------------| ------- | -------- |
| `Accounts` | [QueryAccountsRequest](#cosmos.auth.v1beta1.QueryAccountsRequest) | [QueryAccountsResponse](#cosmos.auth.v1beta1.QueryAccountsResponse) | Accounts returns all the existing accounts | GET|/cosmos/auth/v1beta1/accounts|
| `Accounts` | [QueryAccountsRequest](#cosmos.auth.v1beta1.QueryAccountsRequest) | [QueryAccountsResponse](#cosmos.auth.v1beta1.QueryAccountsResponse) | Accounts returns all the existing accounts

@since Cosmos SDK 0.43 | GET|/cosmos/auth/v1beta1/accounts|
| `Account` | [QueryAccountRequest](#cosmos.auth.v1beta1.QueryAccountRequest) | [QueryAccountResponse](#cosmos.auth.v1beta1.QueryAccountResponse) | Account returns account details based on address. | GET|/cosmos/auth/v1beta1/accounts/{address}|
| `Params` | [QueryParamsRequest](#cosmos.auth.v1beta1.QueryParamsRequest) | [QueryParamsResponse](#cosmos.auth.v1beta1.QueryParamsResponse) | Params queries all parameters. | GET|/cosmos/auth/v1beta1/params|
| `ModuleAccounts` | [QueryModuleAccountsRequest](#cosmos.auth.v1beta1.QueryModuleAccountsRequest) | [QueryModuleAccountsResponse](#cosmos.auth.v1beta1.QueryModuleAccountsResponse) | ModuleAccounts returns all the existing module accounts. | GET|/cosmos/auth/v1beta1/module_accounts|
Expand Down Expand Up @@ -3354,7 +3362,7 @@ VersionInfo is the type for the GetNodeInfoResponse message.
| `build_tags` | [string](#string) | | |
| `go_version` | [string](#string) | | |
| `build_deps` | [Module](#cosmos.base.tendermint.v1beta1.Module) | repeated | |
| `cosmos_sdk_version` | [string](#string) | | |
| `cosmos_sdk_version` | [string](#string) | | @since Cosmos SDK 0.43 |



Expand Down Expand Up @@ -5950,6 +5958,8 @@ MsgVoteResponse defines the Msg/Vote response type.
### MsgVoteWeighted
MsgVoteWeighted defines a message to cast a vote.

@since Cosmos SDK 0.43


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
Expand All @@ -5967,6 +5977,8 @@ MsgVoteWeighted defines a message to cast a vote.
### MsgVoteWeightedResponse
MsgVoteWeightedResponse defines the Msg/VoteWeighted response type.

@since Cosmos SDK 0.43




Expand All @@ -5987,7 +5999,9 @@ Msg defines the bank Msg service.
| ----------- | ------------ | ------------- | ------------| ------- | -------- |
| `SubmitProposal` | [MsgSubmitProposal](#cosmos.gov.v1beta1.MsgSubmitProposal) | [MsgSubmitProposalResponse](#cosmos.gov.v1beta1.MsgSubmitProposalResponse) | SubmitProposal defines a method to create new proposal given a content. | |
| `Vote` | [MsgVote](#cosmos.gov.v1beta1.MsgVote) | [MsgVoteResponse](#cosmos.gov.v1beta1.MsgVoteResponse) | Vote defines a method to add a vote on a specific proposal. | |
| `VoteWeighted` | [MsgVoteWeighted](#cosmos.gov.v1beta1.MsgVoteWeighted) | [MsgVoteWeightedResponse](#cosmos.gov.v1beta1.MsgVoteWeightedResponse) | VoteWeighted defines a method to add a weighted vote on a specific proposal. | |
| `VoteWeighted` | [MsgVoteWeighted](#cosmos.gov.v1beta1.MsgVoteWeighted) | [MsgVoteWeightedResponse](#cosmos.gov.v1beta1.MsgVoteWeightedResponse) | VoteWeighted defines a method to add a weighted vote on a specific proposal.

@since Cosmos SDK 0.43 | |
| `Deposit` | [MsgDeposit](#cosmos.gov.v1beta1.MsgDeposit) | [MsgDepositResponse](#cosmos.gov.v1beta1.MsgDepositResponse) | Deposit defines a method to add deposit on a specific proposal. | |

<!-- end services -->
Expand Down
6 changes: 6 additions & 0 deletions proto/cosmos/auth/v1beta1/query.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ option go_package = "github.com/cosmos/cosmos-sdk/x/auth/types";
// Query defines the gRPC querier service.
service Query {
// Accounts returns all the existing accounts
//
// Since: cosmos-sdk 0.43
rpc Accounts(QueryAccountsRequest) returns (QueryAccountsResponse) {
option (google.api.http).get = "/cosmos/auth/v1beta1/accounts";
}
Expand Down Expand Up @@ -49,12 +51,16 @@ service Query {
}

// QueryAccountsRequest is the request type for the Query/Accounts RPC method.
//
// Since: cosmos-sdk 0.43
message QueryAccountsRequest {
// pagination defines an optional pagination for the request.
cosmos.base.query.v1beta1.PageRequest pagination = 1;
}

// QueryAccountsResponse is the response type for the Query/Accounts RPC method.
//
// Since: cosmos-sdk 0.43
message QueryAccountsResponse {
// accounts are the existing accounts
repeated google.protobuf.Any accounts = 1 [(cosmos_proto.accepts_interface) = "AccountI"];
Expand Down
4 changes: 4 additions & 0 deletions proto/cosmos/authz/v1beta1/authz.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ option (gogoproto.goproto_getters_all) = false;

// GenericAuthorization gives the grantee unrestricted permissions to execute
// the provided method on behalf of the granter's account.
//
// Since: cosmos-sdk 0.43
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For authz, I added this comment on all messages, and on the Query and Msg services.

Would it be possible to add it on the top-level package only?

syntax = "proto3";
// Since: cosmos-sdk 0.43
package cosmos.authz.v1beta1;

(note: that's what I did for cosmos.base.reflection.v2alpha1 for now, because there's a lot of stuff inside that file).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question. I agree there should be package-level documentation. However, there does not seem to be a point in the *.proto definitions where a package is created. It's created implicitly once you assign messages to it and as a consequence this is spread across multiple files.

In ts-proto it looks like file-level comments in the very top are copied to the .ts output, but later comments and package comments are not:

--- a/proto/cosmos/auth/v1beta1/auth.proto
+++ b/proto/cosmos/auth/v1beta1/auth.proto
@@ -1,4 +1,9 @@
+// Foo
 syntax = "proto3";
+
+// Bar
+
+// Since: cosmos-sdk 0.42
 package cosmos.auth.v1beta1;
 
 import "cosmos_proto/cosmos.proto";

becomes

--- a/src/cosmos/auth/v1beta1/auth.ts
+++ b/src/cosmos/auth/v1beta1/auth.ts
@@ -5,6 +5,8 @@ import { Any } from "../../../google/protobuf/any";
 
 export const protobufPackage = "cosmos.auth.v1beta1";
 
+/** Foo */
+
 /**
  * BaseAccount defines a base account type. It contains all the necessary fields
  * for basic accou

So what about putting it in the top of the file?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For a dev that imports CosmJS, would their IDE intellisense show "Foo" somewhere?

It would be ideal if that comment showed up everytime they typed cosmos.authz{...}

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For a dev that imports CosmJS, would their IDE intellisense show "Foo" somewhere?

No, but at least its visible when you dig into it or have it available for support.

It would be ideal if that comment showed up everytime they typed cosmos.authz{...}

Unfortunately we don't get the proto packages bundled into a common object. They are imported by file like this. See also cosmos/cosmjs#647.

Copy link
Contributor Author

@amaury1093 amaury1093 Oct 26, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally I also find it more elegant to put it in the top of the file. I did that in f74fd81.

ts-proto outputs the comments just fine, it would be great to get an idea on other languages (e.g. Rust) too. Duplicating those comments is cumbersome, but also safer (will be outputed on intellisense0. Any thoughts @aaronc ?

message GenericAuthorization {
option (cosmos_proto.implements_interface) = "Authorization";

Expand All @@ -20,6 +22,8 @@ message GenericAuthorization {

// Grant gives permissions to execute
// the provide method with expiration time.
//
// Since: cosmos-sdk 0.43
message Grant {
google.protobuf.Any authorization = 1 [(cosmos_proto.accepts_interface) = "Authorization"];
google.protobuf.Timestamp expiration = 2 [(gogoproto.stdtime) = true, (gogoproto.nullable) = false];
Expand Down
4 changes: 4 additions & 0 deletions proto/cosmos/authz/v1beta1/event.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ import "cosmos_proto/cosmos.proto";
option go_package = "github.com/cosmos/cosmos-sdk/x/authz";

// EventGrant is emitted on Msg/Grant
//
// Since: cosmos-sdk 0.43
message EventGrant {
// Msg type URL for which an autorization is granted
string msg_type_url = 2;
Expand All @@ -16,6 +18,8 @@ message EventGrant {
}

// EventRevoke is emitted on Msg/Revoke
//
// Since: cosmos-sdk 0.43
message EventRevoke {
// Msg type URL for which an autorization is revoked
string msg_type_url = 2;
Expand Down
4 changes: 4 additions & 0 deletions proto/cosmos/authz/v1beta1/genesis.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,15 @@ import "cosmos_proto/cosmos.proto";
option go_package = "github.com/cosmos/cosmos-sdk/x/authz";

// GenesisState defines the authz module's genesis state.
//
// Since: cosmos-sdk 0.43
message GenesisState {
repeated GrantAuthorization authorization = 1 [(gogoproto.nullable) = false];
}

// GrantAuthorization defines the GenesisState/GrantAuthorization type.
//
// Since: cosmos-sdk 0.43
message GrantAuthorization {
string granter = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
string grantee = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
Expand Down
10 changes: 10 additions & 0 deletions proto/cosmos/authz/v1beta1/query.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ import "cosmos_proto/cosmos.proto";
option go_package = "github.com/cosmos/cosmos-sdk/x/authz";

// Query defines the gRPC querier service.
//
// Since: cosmos-sdk 0.43
service Query {
// Returns list of `Authorization`, granted to the grantee by the granter.
rpc Grants(QueryGrantsRequest) returns (QueryGrantsResponse) {
Expand All @@ -22,6 +24,8 @@ service Query {
}

// QueryGrantsRequest is the request type for the Query/Grants RPC method.
//
// Since: cosmos-sdk 0.43
message QueryGrantsRequest {
string granter = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
string grantee = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
Expand All @@ -32,6 +36,8 @@ message QueryGrantsRequest {
}

// QueryGrantsResponse is the response type for the Query/Authorizations RPC method.
//
// Since: cosmos-sdk 0.43
message QueryGrantsResponse {
// authorizations is a list of grants granted for grantee by granter.
repeated cosmos.authz.v1beta1.Grant grants = 1;
Expand All @@ -40,6 +46,8 @@ message QueryGrantsResponse {
}

// QueryGranterGrantsRequest is the request type for the Query/GranterGrants RPC method.
//
// Since: cosmos-sdk 0.43
message QueryGranterGrantsRequest {
string granter = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

Expand All @@ -48,6 +56,8 @@ message QueryGranterGrantsRequest {
}

// QueryGranterGrantsResponse is the response type for the Query/GranterGrants RPC method.
//
// Since: cosmos-sdk 0.43
message QueryGranterGrantsResponse {
// authorizations is a list of grants granted for grantee by granter.
repeated cosmos.authz.v1beta1.Grant grants = 1;
Expand Down
14 changes: 14 additions & 0 deletions proto/cosmos/authz/v1beta1/tx.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ option go_package = "github.com/cosmos/cosmos-sdk/x/authz";
option (gogoproto.goproto_getters_all) = false;

// Msg defines the authz Msg service.
//
// Since: cosmos-sdk 0.43
service Msg {
// Grant grants the provided authorization to the grantee on the granter's
// account with the provided expiration time. If there is already a grant
Expand All @@ -31,6 +33,8 @@ service Msg {

// MsgGrant is a request type for Grant method. It declares authorization to the grantee
// on behalf of the granter with the provided expiration time.
//
// Since: cosmos-sdk 0.43
message MsgGrant {
string granter = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
string grantee = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
Expand All @@ -39,13 +43,17 @@ message MsgGrant {
}

// MsgExecResponse defines the Msg/MsgExecResponse response type.
//
// Since: cosmos-sdk 0.43
message MsgExecResponse {
repeated bytes results = 1;
}

// MsgExec attempts to execute the provided messages using
// authorizations granted to the grantee. Each message should have only
// one signer corresponding to the granter of the authorization.
//
// Since: cosmos-sdk 0.43
message MsgExec {
string grantee = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
// Authorization Msg requests to execute. Each msg must implement Authorization interface
Expand All @@ -55,15 +63,21 @@ message MsgExec {
}

// MsgGrantResponse defines the Msg/MsgGrant response type.
//
// Since: cosmos-sdk 0.43
message MsgGrantResponse {}

// MsgRevoke revokes any authorization with the provided sdk.Msg type on the
// granter's account with that has been granted to the grantee.
//
// Since: cosmos-sdk 0.43
message MsgRevoke {
string granter = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
string grantee = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];;
string msg_type_url = 3;
}

// MsgRevokeResponse defines the Msg/MsgRevokeResponse response type.
//
// Since: cosmos-sdk 0.43
message MsgRevokeResponse {}
8 changes: 8 additions & 0 deletions proto/cosmos/bank/v1beta1/bank.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,13 +85,21 @@ message Metadata {
// displayed in clients.
string display = 4;
// name defines the name of the token (eg: Cosmos Atom)
//
// Since: cosmos-sdk 0.43
string name = 5;
// symbol is the token symbol usually shown on exchanges (eg: ATOM). This can
// be the same as the display.
//
// Since: cosmos-sdk 0.43
string symbol = 6;
// URI to a document (on or off-chain) that contains additional information. Optional.
//
// Since: cosmos-sdk 0.45
string uri = 7 [(gogoproto.customname) = "URI"];
// URIHash is a sha256 hash of a document pointed by URI. It's used to verify that
// the document didn't change. Optional.
//
// Since: cosmos-sdk 0.45
string uri_hash = 8 [(gogoproto.customname) = "URIHash"];
}
4 changes: 4 additions & 0 deletions proto/cosmos/bank/v1beta1/query.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,8 @@ message QueryTotalSupplyRequest {
option (gogoproto.goproto_getters) = false;

// pagination defines an optional pagination for the request.
//
// Since: cosmos-sdk 0.43
cosmos.base.query.v1beta1.PageRequest pagination = 1;
}

Expand All @@ -114,6 +116,8 @@ message QueryTotalSupplyResponse {
[(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"];

// pagination defines the pagination in the response.
//
// Since: cosmos-sdk 0.43
cosmos.base.query.v1beta1.PageResponse pagination = 2;
}

Expand Down
2 changes: 2 additions & 0 deletions proto/cosmos/base/query/v1beta1/pagination.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,8 @@ message PageRequest {
bool count_total = 4;

// reverse is set to true if results are to be returned in the descending order.
//
// Since: cosmos-sdk 0.43
bool reverse = 5;
}

Expand Down
1 change: 1 addition & 0 deletions proto/cosmos/base/reflection/v2alpha1/reflection.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
syntax = "proto3";
// Since: cosmos-sdk 0.43
package cosmos.base.reflection.v2alpha1;

import "google/api/annotations.proto";
Expand Down
2 changes: 2 additions & 0 deletions proto/cosmos/base/store/v1beta1/listening.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ option go_package = "github.com/cosmos/cosmos-sdk/store/types";
// StoreKVPair is a KVStore KVPair used for listening to state changes (Sets and Deletes)
// It optionally includes the StoreKey for the originating KVStore and a Boolean flag to distinguish between Sets and
// Deletes
//
// Since: cosmos-sdk 0.43
message StoreKVPair {
string store_key = 1; // the store key for the KVStore this pair originates from
bool delete = 2; // true indicates a delete operation, false indicates a set operation
Expand Down
1 change: 1 addition & 0 deletions proto/cosmos/base/tendermint/v1beta1/query.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,7 @@ message VersionInfo {
string build_tags = 5;
string go_version = 6;
repeated Module build_deps = 7;
// Since: cosmos-sdk 0.43
string cosmos_sdk_version = 8;
}

Expand Down
1 change: 1 addition & 0 deletions proto/cosmos/crypto/secp256r1/keys.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
syntax = "proto3";
// Since: cosmos-sdk 0.43
package cosmos.crypto.secp256r1;

import "gogoproto/gogo.proto";
Expand Down
3 changes: 3 additions & 0 deletions proto/cosmos/gov/v1beta1/gov.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@ enum VoteOption {
}

// WeightedVoteOption defines a unit of vote for vote split.
//
// Since: cosmos-sdk 0.43
message WeightedVoteOption {
VoteOption option = 1;
string weight = 2 [
Expand Down Expand Up @@ -134,6 +136,7 @@ message Vote {
// if and only if `len(options) == 1` and that option has weight 1. In all
// other cases, this field will default to VOTE_OPTION_UNSPECIFIED.
VoteOption option = 3 [deprecated = true];
// Since: cosmos-sdk 0.43
repeated WeightedVoteOption options = 4 [(gogoproto.nullable) = false];
}

Expand Down
Loading