docs: fix grammar and spelling errors #25139
Conversation
📝 WalkthroughWalkthroughDocumentation-only updates across multiple build docs: grammar, wording, and formatting corrections; one note replaced about BeginBlocker/EndBlocker event emission; added a Buf “Workspace” subsection and minor clarifications in tooling docs. No code, interfaces, or public APIs are modified. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~7 minutes ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🔭 Outside diff range comments (1)
docs/docs/build/building-modules/05-protobuf-annotations.md (1)
69-75: Fix incorrect example: show method/field/message variants.
The block repeatsmethod_added_inthree times; it should demonstrate the three distinct annotations discussed above.-```proto -option (cosmos_proto.method_added_in) = "cosmos-sdk v0.50.1"; -option (cosmos_proto.method_added_in) = "x/epochs v1.0.0"; -option (cosmos_proto.method_added_in) = "simapp v24.0.0"; -``` +```proto +option (cosmos_proto.method_added_in) = "cosmos-sdk v0.50.1"; +option (cosmos_proto.field_added_in) = "x/epochs v1.0.0"; +option (cosmos_proto.message_added_in) = "simapp v24.0.0"; +```
🧹 Nitpick comments (14)
docs/docs/build/building-modules/15-depinject.md (1)
39-39: Tighten phrasing: “is able to decide” → “can decide”Shorter and equally clear.
- Taking `group` as an example, a chain developer is able to decide, thanks to `uint64 max_metadata_len`, what the maximum metadata length allowed for a group proposal is. + Taking `group` as an example, a chain developer can decide, thanks to `uint64 max_metadata_len`, what the maximum metadata length allowed for a group proposal is.docs/docs/build/building-modules/16-testing.md (2)
10-10: Use “similarly” for concisionReads more naturally.
-It is advised, as a chain developer, to test your application and modules in a similar way to the SDK. +As a chain developer, test your application and modules similarly to the SDK.
49-49: Optional: more direct voiceConsider addressing the reader directly.
-We can then create unit tests using the newly created `Keeper` instance. +You can then create unit tests using the newly created `Keeper` instance.docs/docs/build/building-modules/08-genesis.md (2)
20-20: Tighten wording; avoid repeated “defined”.
Current sentence repeats “defined” and is a bit clunky.-The subset of the genesis state defined by a given module is generally defined in a `genesis.proto` file ([more info](../../learn/advanced/05-encoding.md#gogoproto) on how to define protobuf messages). The struct defining the module's subset of the genesis state is usually called `GenesisState` and contains all the module-related values that need to be initialized during the genesis process. +A module’s subset of the genesis state is generally specified in a `genesis.proto` file ([more info](../../learn/advanced/05-encoding.md#gogoproto) on how to define protobuf messages). The struct for this subset is usually called `GenesisState` and contains all module-related values that must be initialized during genesis.
32-32: Clarify and de-redundify: “method is a function”; pluralize “values”.
Also keeps the sentence concise.-The `DefaultGenesis()` method is a simple function that calls the constructor function for `GenesisState` with the default value for each parameter. See an example from the `auth` module: +The `DefaultGenesis()` function constructs a `GenesisState` with default values for each parameter. See an example from the `auth` module:docs/docs/build/building-modules/06-beginblock-endblock.md (2)
21-21: Improve accuracy and grammar (ABCI++ names; simplify “prior to”).
Use the proper ABCI++ method names and tighten the phrasing.-In 0.47.0, Prepare and Process Proposal were added that allow app developers to do arbitrary work at those phases, but they do not influence the work that will be done in BeginBlock. If an application requires `BeginBlock` to execute prior to any sort of work is done then this is not possible today (0.50.0). +In v0.47, `PrepareProposal` and `ProcessProposal` were added, allowing app developers to perform arbitrary work during those phases, but they do not affect what happens in `BeginBlock`. As of v0.50, requiring `BeginBlock` to execute before any work is done is not supported.[ suggest_nitpick ]
28-30: Unify bullet phrasing; prefer “state transitions”; reference EventManager consistently.
Minor editorial pass for consistency and clarity.-* They generally use the [`keeper`](./06-keeper.md) and [`ctx`](../../learn/advanced/02-context.md) to retrieve information about the latest state. -* If needed, they use the `keeper` and `ctx` to trigger state-transitions. -* If needed, they can emit [`events`](../../learn/advanced/08-events.md) via the `ctx`'s `EventManager`. +* Generally use the [`keeper`](./06-keeper.md) and [`ctx`](../../learn/advanced/02-context.md) to read the latest state. +* When needed, trigger state transitions via the `keeper` and `ctx`. +* When needed, emit [`events`](../../learn/advanced/08-events.md) via `ctx.EventManager`.docs/docs/build/building-modules/05-protobuf-annotations.md (4)
59-59: Name the option explicitly; fix grammar.
It’s the option that tools consume, not “the implement interface”.-The implement interface is used to provide information to client tooling like [telescope](https://github.com/cosmology-tech/telescope) on how to encode and decode protobuf messages. +The `implements_interface` option provides information to client tooling (for example, [Telescope](https://github.com/cosmology-tech/telescope)) on how to encode and decode protobuf messages.
79-82: Avoid contradiction: codec removed vs. “provide information to the codec”.
Clarify that annotations exist for Amino-compatible JSON in clients; new modules need not use them.-The amino codec was removed in `v0.50+`, this means there is no need to register `legacyAminoCodec`. To replace the amino codec, Amino protobuf annotations are used to provide information to the amino codec on how to encode and decode protobuf messages. - -Amino annotations are only used for backwards compatibility with amino. New modules are not required to use amino annotations. +The Amino codec was removed in `v0.50+`, so there is no need to register `legacyAminoCodec`. For backward compatibility, use Amino protobuf annotations to guide Amino‑compatible JSON encoding/decoding in clients. + +Amino annotations exist only for backward compatibility; new modules are not required to use them.
87-91: Trim wordiness (“in order for them to”).-Name specifies the amino name that would show up for the user in order for them to see which message they are signing. +Name specifies the Amino name that appears to users so they can see which message they are signing.
99-103: Trim wordiness; mirror “Name” phrasing.-Field name specifies the amino name that would show up for the user in order for them to see which field they are signing. +Field_Name specifies the Amino name that appears to users so they can see which field they are signing.docs/docs/build/tooling/00-protobuf.md (3)
25-25: Minor grammar/style: apostrophe, capitalization, article.-[Buf](https://buf.build) is a protobuf tool that abstracts the need to use the complicated `protoc` toolchain on top of various other things that ensure you are using protobuf in accordance with the majority of the ecosystem. Within the cosmos-sdk repository there are a few files that have a buf prefix. Lets start with the top level and then dive into the various directories. +[Buf](https://buf.build) is a protobuf tool that abstracts the need to use the complicated `protoc` toolchain, and it helps ensure your usage aligns with the broader ecosystem. Within the Cosmos SDK repository, there are a few files with a Buf prefix. Let's start at the top level and then dive into the various directories.
81-81: Tighten terminology: queries/messages; Query/Msg services.-`buf.gen.swagger.yaml` generates the swagger documentation for the query and messages of the chain. This will only define the REST API endpoints that were defined in the query and msg servers. You can find examples of this [here](https://github.com/cosmos/cosmos-sdk/blob/main/proto/cosmos/bank/v1beta1/query.proto#L19) +`buf.gen.swagger.yaml` generates Swagger documentation for the chain’s queries and messages. It only defines REST API endpoints exposed by the Query and Msg services. You can find examples [here](https://github.com/cosmos/cosmos-sdk/blob/main/proto/cosmos/bank/v1beta1/query.proto#L19).
93-93: Clarify intent of buf.lock guidance.
Make it explicit you shouldn’t copy the SDK’s lock file.-This is an autogenerated file based on the dependencies required by the `.gen` files. There is no need to copy the current one. If you depend on cosmos-sdk proto definitions a new entry for the Cosmos SDK will need to be provided. The dependency you will need to use is `buf.build/cosmos/cosmos-sdk`. +This is an autogenerated file based on the dependencies required by the `.gen` files. You don’t need to copy the Cosmos SDK’s lock file; generate your own. If you depend on Cosmos SDK proto definitions, ensure an entry for `buf.build/cosmos/cosmos-sdk` is present.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Knowledge Base: Disabled due to Reviews > Disable Knowledge Base setting
📒 Files selected for processing (12)
docs/docs/build/building-modules/05-protobuf-annotations.md(4 hunks)docs/docs/build/building-modules/06-beginblock-endblock.md(1 hunks)docs/docs/build/building-modules/06-keeper.md(1 hunks)docs/docs/build/building-modules/08-genesis.md(2 hunks)docs/docs/build/building-modules/09-module-interfaces.md(1 hunks)docs/docs/build/building-modules/11-structure.md(1 hunks)docs/docs/build/building-modules/14-simulator.md(1 hunks)docs/docs/build/building-modules/15-depinject.md(1 hunks)docs/docs/build/building-modules/16-testing.md(2 hunks)docs/docs/build/building-modules/17-preblock.md(1 hunks)docs/docs/build/packages/README.md(1 hunks)docs/docs/build/tooling/00-protobuf.md(4 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/docs/build/building-modules/16-testing.md
[style] ~10-~10: Consider replacing this phrase with the adverb “similarly” to avoid wordiness.
Context: ...r, to test your application and modules in a similar way to the SDK. The rationale behind testi...
(IN_A_X_MANNER)
docs/docs/build/building-modules/15-depinject.md
[style] ~39-~39: As a shorter alternative for ‘able to’, consider using “can”.
Context: ...groupas an example, a chain developer is able to decide, thanks touint64 max_metadata_...
(BE_ABLE_TO)
docs/docs/build/building-modules/05-protobuf-annotations.md
[style] ~87-~87: ‘in order for them to’ might be wordy. Consider a shorter alternative.
Context: ...no name that would show up for the user in order for them to see which message they are signing. ``...
(EN_WORDINESS_PREMIUM_IN_ORDER_FOR_THEM_TO)
[style] ~99-~99: ‘in order for them to’ might be wordy. Consider a shorter alternative.
Context: ...no name that would show up for the user in order for them to see which field they are signing. ```p...
(EN_WORDINESS_PREMIUM_IN_ORDER_FOR_THEM_TO)
docs/docs/build/building-modules/06-beginblock-endblock.md
[style] ~21-~21: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ...cation requires BeginBlock to execute prior to any sort of work is done then this is n...
(EN_WORDINESS_PREMIUM_PRIOR_TO)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Summary
🔇 Additional comments (8)
docs/docs/build/building-modules/06-keeper.md (1)
19-19: LGTM: improved plurality/readabilityPluralizing “developer” to “developers” reads better. No further edits needed here.
docs/docs/build/building-modules/11-structure.md (1)
85-85: LGTM: clearer phrasing“Learn more about how to write module specs” is clearer. Good change.
docs/docs/build/building-modules/09-module-interfaces.md (1)
135-136: LGTM: code fence formatting fixedProperly closing the fenced block improves Markdown rendering.
docs/docs/build/building-modules/14-simulator.md (1)
75-75: LGTM: correct spelling (“unmarshals”)Accurate term for converting bytes to a struct.
docs/docs/build/building-modules/17-preblock.md (1)
24-24: LGTM: pluralization matches semantics“consensus parameters” (plural) is correct in this context.
docs/docs/build/packages/README.md (1)
7-7: LGTM: grammar fix“can be used” is correct here. Thanks.
docs/docs/build/building-modules/06-beginblock-endblock.md (1)
25-25: Subject–verb agreement fix looks good.
No further action.docs/docs/build/tooling/00-protobuf.md (1)
53-53: LGTM on clarity fix.
“The above diagram shows …” reads correctly.
2 participants
Description
Summary by CodeRabbit