R4R: Docs: Building-modules section 2nd part #5037

gamarin2 · 2019-09-12T13:35:13Z

Finishing building-modules section of the new docs.

Targeted PR against correct branch (see CONTRIBUTING.md)
Linked to github-issue with discussion and accepted design OR link to spec that describes this work.
Wrote tests
Updated relevant documentation (docs/)
Added a relevant changelog entry to the Unreleased section in CHANGELOG.md
Re-reviewed Files changed in the github PR explorer

For Admin Use:

Added appropriate labels to PR (ex. wip, ready-for-review, docs)
Reviewers Assigned
Squashed all commits, uses message "Merge pull request #XYZ: [title]" (coding standards)

codecov · 2019-09-12T17:43:31Z

Codecov Report

Merging #5037 into master-docs will not change coverage.
The diff coverage is n/a.

@@             Coverage Diff              @@
##           master-docs    #5037   +/-   ##
============================================
  Coverage        54.85%   54.85%           
============================================
  Files              305      305           
  Lines            18494    18494           
============================================
  Hits             10144    10144           
  Misses            7595     7595           
  Partials           755      755

docs/building-modules/beginblock-endblock.md

docs/building-modules/invariants.md

docs/building-modules/messages-and-queries.md

docs/building-modules/module-manager.md

docs/core/baseapp.md

Co-Authored-By: Hans Schoenburg <[email protected]>

alexanderbez · 2019-09-16T17:13:16Z

Is this ready to merge @gamarin2? I also recommend merging the latest master into master-docs prior to merging this if possible.

gamarin2 · 2019-09-16T18:20:06Z

@alexanderbez well I'd like 1 more review if possible, but otherwise yes

docs/building-modules/handler.md

docs/building-modules/querier.md

Addressed

fedekunze · 2019-10-01T16:29:29Z

@gamarin2 please merge master into master-docs to fix CI

…cosmos-sdk into gamarin/building-modules

hschoenburg

some small comments.

hschoenburg · 2019-10-15T19:44:29Z

docs/building-modules/beginblock-endblock.md

+
+When needed, `BeginBlocker` and `EndBlocker` are implemented as part of the [`AppModule` interface](./module-manager.md#appmodule). The `BeginBlock` and `EndBlock` methods of the interface implemented in `module.go` generally defer to `BeginBlocker` and `EndBlocker` methods respectively, which are usually implemented in a `abci.go` file. 
+
+The actual implementation of `BeginBlocker` and `EndBlocker` are very similar to that of a [`handler`](./handler.md):


Would be good to add a line describing app.ModuleManager.SetOrderBeginBlockers and SetOrderEndBlockers

hschoenburg · 2019-10-15T19:50:31Z

docs/building-modules/beginblock-endblock.md

+
+## Synopsis
+
+`BeginBlocker` and `EndBlocker` are optional methods module developers can implement in their module. They will be triggered at the beginning and at the end of each block respectively. 


maybe add something along the lines of "They will be triggered at the beginning and at the end of each block by the BeginBlock and EndBlock ABCI messages sent from Tendermint."

hschoenburg · 2019-10-15T19:53:38Z

docs/building-modules/genesis.md

+### `InitGenesis`
+
+The `InitGenesis` method is executed during [`InitChain`](../core/baseapp.md#initchain) when the application is first started. Given a `GenesisState`, it initializes the subset of the state managed by the module by using the module's [`keeper`](./keeper.md) setter function on each parameter within the `GenesisState`. 


probably want to mention ModuleManager.SetOrderInitGenesis here too
https://github.com/cosmos/gaia/blob/master/app/app.go#L203

hschoenburg · 2019-10-15T20:00:41Z

docs/building-modules/invariants.md

+The `InvariantRegistry` is a registry where the `Invariant`s of all the modules of an application are registered. There is only one `InvariantRegistry` per **application**, meaning module developers need not implement their own `InvariantRegistry` when building a module. All module developers need to do is to register their modules' invariants in the `InvariantRegistry`, as explained in the section above. 
+
+Typically, the `InvariantRegistry` is implemented as a specific module (the most used implementation is that of the [`crisis` module](https://github.com/cosmos/cosmos-sdk/blob/master/x/crisis/)). This module must implement an object that follow the [`sdk.InvariantRegistry` interface](https://github.com/cosmos/cosmos-sdk/blob/master/types/invariant.go#L14-L17). 


this paragraph is confusing. -- does the SDK contain the only instance of the InvariantRegistry ? Does the crisis module contain another instance?

hschoenburg · 2019-10-15T20:04:08Z

docs/building-modules/keeper.md

+- `storeKey`s grant access to the store(s) of the [multistore](../core/store.md) managed by the module. They should always remain unexposed to external modules. 
+- A [codec `cdc`](../core/encoding.md), used to marshall and unmarshall struct to/from `[]byte`. 
+
+Of course, it is possible to define different types of internal `keeper`s for the same module (e.g. a read-only `keeper`). Each type of `keeper` comes with its own constructor function, which is called from the [application's constructor function](../basics/app-anatomy.md). This is where `keeper`s are instanciated, and where developers make sure to pass correct instances of modules' `keeper`s to other modules that require it. 


instantiated

hschoenburg · 2019-10-15T20:07:59Z

docs/building-modules/keeper.md

+
+## Synopsis
+
+`Keeper`s refer to a Cosmos SDK abstraction whose role is to manage access to the subset of the state defined by various modules. `Keeper`s are module-specific, i.e. the subset of state defined by a module can only be accessed by a `keeper` defined in said module. If a module needs to access the subset of state defined by another module, a reference to the second module's internal `keeper` needs to be passed to the first one. This is done in `app.go` during the instantiation of module keepers.


Perhaps add a line describing what the underlying KVStore is? https://github.com/tendermint/iavl

hschoenburg · 2019-10-15T20:09:33Z

docs/building-modules/messages-and-queries.md

+```
+
+The `Msg` is typically accompagnied by a standard constructor function, that is called from one of the [module's interface](./module-interface). `message`s also need to implement the [`Msg`](https://github.com/cosmos/cosmos-sdk/blob/master/types/tx_msg.go#L7-L29) interface, which contains the following methods:


accompanied

hschoenburg · 2019-10-15T20:11:38Z

docs/building-modules/messages-and-queries.md

+## Queries
+
+A `query` is a request for information made by end-users of applications through an interface and processed by a full-node. A `query` is received by a full-node through its consensus engine and relayed to the application via the ABCI. It is then routed to the appropriate module via `baseapp`'s `queryrouter` so that it can be processed by the module's [`querier`](./querier.md). For a deeper look at the lifecycle of a `query`, click [here](../interfaces/query-lifecycle.md). 


maybe mention that these queries should not be confused with the REST server and its endpoints?

hschoenburg · 2019-10-15T20:15:24Z

docs/building-modules/module-manager.md

+The module manager is used throughout the application whenever an action on a collection of modules is required. It implements the following methods:
+
+- `NewManager(modules ...AppModule)`: Constructor function. It takes a list of the application's `AppModule`s and builds a new `Manager`. It is generally called from the application's main [constructor function](../basics/app-anatomy.md#constructor-function).
+- `SetOrderInitGenesis(moduleNames ...string)`: Sets the order in which the [`InitGenesis`](./genesis.md#initgenesis) function of each module will be called when the application is first started. This function is generally called from the application's main [constructor function](../basics/app-anatomy.md#constructor-function).


ah great maybe just provide a link to this section above when discussing InitGenesis and BeginBlock

hschoenburg · 2019-10-15T20:18:25Z

oops submitted my review too late sorrry. Nothing major, could probably be ignored

gamarin2 · 2019-10-16T13:08:31Z

No worries @hschoenburg. I will integrate your comments in the final docs-cleanup PR

gamarin2 added 8 commits August 20, 2019 19:24

working

a6788cd

working

d96abfd

working

f38fd48

finish messages and queries

c7ddc70

handler

f7b6fc3

querier

8b1ac72

querier2

5162d2e

keeper

b4d1657

gamarin2 changed the title ~~Docs: Building-modules section~~ Docs: Building-modules section 2nd part Sep 12, 2019

genesis

190c5d3

gamarin2 added 2 commits September 13, 2019 17:40

finish

d2a2d91

Merge branch 'master-docs' into gamarin/building-modules

f3d307a

gamarin2 marked this pull request as ready for review September 13, 2019 15:42

gamarin2 requested review from alessio, alexanderbez, fedekunze, jackzampolin and rigelrozanski as code owners September 13, 2019 15:42

gamarin2 requested a review from hschoenburg September 13, 2019 15:42

gamarin2 changed the title ~~Docs: Building-modules section 2nd part~~ R4R: Docs: Building-modules section 2nd part Sep 13, 2019

hschoenburg previously requested changes Sep 13, 2019

View reviewed changes

gamarin2 and others added 3 commits September 16, 2019 12:30

Apply suggestions from code review

c09597f

Co-Authored-By: Hans Schoenburg <[email protected]>

hans review

e20c6d3

Update docs/core/baseapp.md

628ad72

Co-Authored-By: Hans Schoenburg <[email protected]>

fedekunze added T:Docs Changes and features related to documentation. R4R labels Oct 1, 2019

fedekunze approved these changes Oct 1, 2019

View reviewed changes

docs/building-modules/handler.md Outdated Show resolved Hide resolved

docs/building-modules/handler.md Outdated Show resolved Hide resolved

docs/building-modules/querier.md Outdated Show resolved Hide resolved

Apply suggestions from code review

01e79c8

gamarin2 added 2 commits October 11, 2019 16:19

merge

bc6afa6

Merge branch 'gamarin/building-modules' of https://github.com/cosmos/…

c44e476

…cosmos-sdk into gamarin/building-modules

gamarin2 merged commit d3a168a into master-docs Oct 11, 2019

gamarin2 deleted the gamarin/building-modules branch October 11, 2019 14:52

hschoenburg reviewed Oct 15, 2019

View reviewed changes

gamarin2 mentioned this pull request Dec 9, 2019

[R4R] New docs V1 (merge master-docs to master) #5379

Merged

11 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

R4R: Docs: Building-modules section 2nd part #5037

R4R: Docs: Building-modules section 2nd part #5037

gamarin2 commented Sep 12, 2019 •

edited

Loading

codecov bot commented Sep 12, 2019 •

edited

Loading

alexanderbez commented Sep 16, 2019

gamarin2 commented Sep 16, 2019

fedekunze commented Oct 1, 2019

hschoenburg left a comment

hschoenburg Oct 15, 2019

hschoenburg Oct 15, 2019

hschoenburg Oct 15, 2019

hschoenburg Oct 15, 2019

hschoenburg Oct 15, 2019

hschoenburg Oct 15, 2019

hschoenburg Oct 15, 2019

hschoenburg Oct 15, 2019

hschoenburg Oct 15, 2019

hschoenburg commented Oct 15, 2019

gamarin2 commented Oct 16, 2019


		When needed, `BeginBlocker` and `EndBlocker` are implemented as part of the [`AppModule` interface](./module-manager.md#appmodule). The `BeginBlock` and `EndBlock` methods of the interface implemented in `module.go` generally defer to `BeginBlocker` and `EndBlocker` methods respectively, which are usually implemented in a `abci.go` file.

		The actual implementation of `BeginBlocker` and `EndBlocker` are very similar to that of a [`handler`](./handler.md):


		## Synopsis

		`BeginBlocker` and `EndBlocker` are optional methods module developers can implement in their module. They will be triggered at the beginning and at the end of each block respectively.

		### `InitGenesis`

		The `InitGenesis` method is executed during [`InitChain`](../core/baseapp.md#initchain) when the application is first started. Given a `GenesisState`, it initializes the subset of the state managed by the module by using the module's [`keeper`](./keeper.md) setter function on each parameter within the `GenesisState`.

		The `InvariantRegistry` is a registry where the `Invariant`s of all the modules of an application are registered. There is only one `InvariantRegistry` per application, meaning module developers need not implement their own `InvariantRegistry` when building a module. All module developers need to do is to register their modules' invariants in the `InvariantRegistry`, as explained in the section above.

		Typically, the `InvariantRegistry` is implemented as a specific module (the most used implementation is that of the [`crisis` module](https://github.com/cosmos/cosmos-sdk/blob/master/x/crisis/)). This module must implement an object that follow the [`sdk.InvariantRegistry` interface](https://github.com/cosmos/cosmos-sdk/blob/master/types/invariant.go#L14-L17).


		## Synopsis

		`Keeper`s refer to a Cosmos SDK abstraction whose role is to manage access to the subset of the state defined by various modules. `Keeper`s are module-specific, i.e. the subset of state defined by a module can only be accessed by a `keeper` defined in said module. If a module needs to access the subset of state defined by another module, a reference to the second module's internal `keeper` needs to be passed to the first one. This is done in `app.go` during the instantiation of module keepers.

		```

		The `Msg` is typically accompagnied by a standard constructor function, that is called from one of the [module's interface](./module-interface). `message`s also need to implement the [`Msg`](https://github.com/cosmos/cosmos-sdk/blob/master/types/tx_msg.go#L7-L29) interface, which contains the following methods:

		## Queries

		A `query` is a request for information made by end-users of applications through an interface and processed by a full-node. A `query` is received by a full-node through its consensus engine and relayed to the application via the ABCI. It is then routed to the appropriate module via `baseapp`'s `queryrouter` so that it can be processed by the module's [`querier`](./querier.md). For a deeper look at the lifecycle of a `query`, click [here](../interfaces/query-lifecycle.md).

R4R: Docs: Building-modules section 2nd part #5037

R4R: Docs: Building-modules section 2nd part #5037

Conversation

gamarin2 commented Sep 12, 2019 • edited Loading

codecov bot commented Sep 12, 2019 • edited Loading

Codecov Report

alexanderbez commented Sep 16, 2019

gamarin2 commented Sep 16, 2019

fedekunze commented Oct 1, 2019

hschoenburg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hschoenburg commented Oct 15, 2019

gamarin2 commented Oct 16, 2019

gamarin2 commented Sep 12, 2019 •

edited

Loading

codecov bot commented Sep 12, 2019 •

edited

Loading