Skip to content

Commit

Permalink
chore: Add "Since:" on proto doc comments (#10434)
Browse files Browse the repository at this point in the history
<!--
The default pull request template is for types feat, fix, or refactor.
For other templates, add one of the following parameters to the url:
- template=docs.md
- template=other.md
-->

## Description

ref: #10406 (reply in thread)

For clients to know whether a protobuf feature is available for a certain SDK version, we decided to use the [`@since` doc comment](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#@since) inside protobuf files.

<!-- Add a description of the changes that this PR introduces and the files that
are the most critical to review. -->

---

### Author Checklist

*All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.*

I have...

- [ ] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] added `!` to the type prefix if API or client breaking change
- [ ] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting))
- [ ] provided a link to the relevant issue or specification
- [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules)
- [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing)
- [ ] added a changelog entry to `CHANGELOG.md`
- [ ] included comments for [documenting Go code](https://blog.golang.org/godoc)
- [ ] updated the relevant documentation or specification
- [ ] reviewed "Files changed" and left comments if necessary
- [ ] confirmed all CI checks have passed

### Reviewers Checklist

*All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.*

I have...

- [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] confirmed `!` in the type prefix if API or client breaking change
- [ ] confirmed all author checklist items have been addressed 
- [ ] reviewed state machine logic
- [ ] reviewed API design and naming
- [ ] reviewed documentation is accurate
- [ ] reviewed tests and test coverage
- [ ] manually tested (if applicable)
  • Loading branch information
amaury1093 authored Oct 27, 2021
1 parent d819692 commit 0a3660d
Show file tree
Hide file tree
Showing 42 changed files with 208 additions and 35 deletions.
17 changes: 9 additions & 8 deletions client/grpc/tmservice/query.pb.go

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

102 changes: 76 additions & 26 deletions docs/core/proto-docs.md

Large diffs are not rendered by default.

6 changes: 6 additions & 0 deletions proto/cosmos/auth/v1beta1/query.proto
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
1 change: 1 addition & 0 deletions proto/cosmos/authz/v1beta1/authz.proto
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
// Since: cosmos-sdk 0.43
syntax = "proto3";
package cosmos.authz.v1beta1;

Expand Down
1 change: 1 addition & 0 deletions proto/cosmos/authz/v1beta1/event.proto
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
// Since: cosmos-sdk 0.43
syntax = "proto3";
package cosmos.authz.v1beta1;

Expand Down
1 change: 1 addition & 0 deletions proto/cosmos/authz/v1beta1/genesis.proto
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
// Since: cosmos-sdk 0.43
syntax = "proto3";
package cosmos.authz.v1beta1;

Expand Down
1 change: 1 addition & 0 deletions proto/cosmos/authz/v1beta1/query.proto
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
// Since: cosmos-sdk 0.43
syntax = "proto3";
package cosmos.authz.v1beta1;

Expand Down
1 change: 1 addition & 0 deletions proto/cosmos/authz/v1beta1/tx.proto
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
// Since: cosmos-sdk 0.43
syntax = "proto3";
package cosmos.authz.v1beta1;

Expand Down
2 changes: 2 additions & 0 deletions proto/cosmos/bank/v1beta1/authz.proto
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ option go_package = "github.com/cosmos/cosmos-sdk/x/bank/types";

// SendAuthorization allows the grantee to spend up to spend_limit coins from
// the granter's account.
//
// Since: cosmos-sdk 0.43
message SendAuthorization {
option (cosmos_proto.implements_interface) = "Authorization";

Expand Down
8 changes: 8 additions & 0 deletions proto/cosmos/bank/v1beta1/bank.proto
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
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
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
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
// Since: cosmos-sdk 0.43
syntax = "proto3";
package cosmos.base.reflection.v2alpha1;

Expand Down
2 changes: 2 additions & 0 deletions proto/cosmos/base/store/v1beta1/listening.proto
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
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
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
// Since: cosmos-sdk 0.43
syntax = "proto3";
package cosmos.crypto.secp256r1;

Expand Down
1 change: 1 addition & 0 deletions proto/cosmos/feegrant/v1beta1/feegrant.proto
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
// Since: cosmos-sdk 0.43
syntax = "proto3";
package cosmos.feegrant.v1beta1;

Expand Down
1 change: 1 addition & 0 deletions proto/cosmos/feegrant/v1beta1/genesis.proto
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
// Since: cosmos-sdk 0.43
syntax = "proto3";
package cosmos.feegrant.v1beta1;

Expand Down
1 change: 1 addition & 0 deletions proto/cosmos/feegrant/v1beta1/query.proto
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
// Since: cosmos-sdk 0.43
syntax = "proto3";
package cosmos.feegrant.v1beta1;

Expand Down
1 change: 1 addition & 0 deletions proto/cosmos/feegrant/v1beta1/tx.proto
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
// Since: cosmos-sdk 0.43
syntax = "proto3";
package cosmos.feegrant.v1beta1;

Expand Down
3 changes: 3 additions & 0 deletions proto/cosmos/gov/v1beta1/gov.proto
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
6 changes: 6 additions & 0 deletions proto/cosmos/gov/v1beta1/tx.proto
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ service Msg {
rpc Vote(MsgVote) returns (MsgVoteResponse);

// VoteWeighted defines a method to add a weighted vote on a specific proposal.
//
// Since: cosmos-sdk 0.43
rpc VoteWeighted(MsgVoteWeighted) returns (MsgVoteWeightedResponse);

// Deposit defines a method to add deposit on a specific proposal.
Expand Down Expand Up @@ -61,6 +63,8 @@ message MsgVote {
message MsgVoteResponse {}

// MsgVoteWeighted defines a message to cast a vote.
//
// Since: cosmos-sdk 0.43
message MsgVoteWeighted {
option (gogoproto.equal) = false;
option (gogoproto.goproto_stringer) = false;
Expand All @@ -73,6 +77,8 @@ message MsgVoteWeighted {
}

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

// MsgDeposit defines a message to submit a deposit to an existing proposal.
Expand Down
4 changes: 4 additions & 0 deletions proto/cosmos/staking/v1beta1/authz.proto
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ import "cosmos/base/v1beta1/coin.proto";
option go_package = "github.com/cosmos/cosmos-sdk/x/staking/types";

// StakeAuthorization defines authorization for delegate/undelegate/redelegate.
//
// Since: cosmos-sdk 0.43
message StakeAuthorization {
option (cosmos_proto.implements_interface) = "Authorization";

Expand All @@ -31,6 +33,8 @@ message StakeAuthorization {
}

// AuthorizationType defines the type of staking module authorization type
//
// Since: cosmos-sdk 0.43
enum AuthorizationType {
// AUTHORIZATION_TYPE_UNSPECIFIED specifies an unknown authorization type
AUTHORIZATION_TYPE_UNSPECIFIED = 0;
Expand Down
2 changes: 2 additions & 0 deletions proto/cosmos/tx/v1beta1/service.proto
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,8 @@ message SimulateRequest {
// Deprecated. Send raw tx bytes instead.
cosmos.tx.v1beta1.Tx tx = 1 [deprecated = true];
// tx_bytes is the raw transaction.
//
// Since: cosmos-sdk 0.43
bytes tx_bytes = 2;
}

Expand Down
2 changes: 2 additions & 0 deletions proto/cosmos/tx/v1beta1/tx.proto
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,8 @@ message AuthInfo {
Fee fee = 2;

// Tip is the optional tip used for meta-transactions.
//
// Since: cosmos-sdk 0.45
Tip tip = 3;
}

Expand Down
7 changes: 7 additions & 0 deletions proto/cosmos/upgrade/v1beta1/query.proto
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@ service Query {
}

// ModuleVersions queries the list of module versions from state.
//
// Since: cosmos-sdk 0.43
rpc ModuleVersions(QueryModuleVersionsRequest) returns (QueryModuleVersionsResponse) {
option (google.api.http).get = "/cosmos/upgrade/v1beta1/module_versions";
}
Expand Down Expand Up @@ -77,11 +79,14 @@ message QueryUpgradedConsensusStateResponse {
option deprecated = true;
reserved 1;

// Since: cosmos-sdk 0.43
bytes upgraded_consensus_state = 2;
}

// QueryModuleVersionsRequest is the request type for the Query/ModuleVersions
// RPC method.
//
// Since: cosmos-sdk 0.43
message QueryModuleVersionsRequest {
// module_name is a field to query a specific module
// consensus version from state. Leaving this empty will
Expand All @@ -91,6 +96,8 @@ message QueryModuleVersionsRequest {

// QueryModuleVersionsResponse is the response type for the Query/ModuleVersions
// RPC method.
//
// Since: cosmos-sdk 0.43
message QueryModuleVersionsResponse {
// module_versions is a list of module names with their consensus versions.
repeated ModuleVersion module_versions = 1;
Expand Down
2 changes: 2 additions & 0 deletions proto/cosmos/upgrade/v1beta1/upgrade.proto
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,8 @@ message CancelSoftwareUpgradeProposal {
}

// ModuleVersion specifies a module and its consensus version.
//
// Since: cosmos-sdk 0.43
message ModuleVersion {
option (gogoproto.equal) = true;
option (gogoproto.goproto_stringer) = true;
Expand Down
2 changes: 2 additions & 0 deletions proto/cosmos/vesting/v1beta1/vesting.proto
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,8 @@ message PeriodicVestingAccount {
// PermanentLockedAccount implements the VestingAccount interface. It does
// not ever release coins, locking them indefinitely. Coins in this account can
// still be used for delegating and for governance votes even while locked.
//
// Since: cosmos-sdk 0.43
message PermanentLockedAccount {
option (gogoproto.goproto_getters) = false;
option (gogoproto.goproto_stringer) = false;
Expand Down
2 changes: 2 additions & 0 deletions store/types/listening.pb.go

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

2 changes: 2 additions & 0 deletions types/query/pagination.pb.go

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

2 changes: 2 additions & 0 deletions types/tx/service.pb.go

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

2 changes: 2 additions & 0 deletions types/tx/tx.pb.go

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

8 changes: 8 additions & 0 deletions x/auth/types/query.pb.go

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

2 changes: 2 additions & 0 deletions x/auth/vesting/types/vesting.pb.go

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

Loading

0 comments on commit 0a3660d

Please sign in to comment.