x/params docs general audit & cleanup (#8295)

* Update doc.go

* Update spec/

* More updates

* Update README

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

x/params/doc.go

@@ -6,9 +6,8 @@ namespace for a parameter store, where keys are prefixed by pre-configured
 subspace names which modules provide. The Keeper has a permission to access all
 existing subspaces.
 
-Subspace can be used by the individual keepers, who needs a private parameter store
-that the other keeper cannot modify. Keeper can be used by the Governance keeper,
-who need to modify any parameter in case of the proposal passes.
+Subspace can be used by the individual keepers, which need a private parameter store
+that the other keepers cannot modify.
 
 Basic Usage:
 
@@ -23,11 +22,11 @@ Basic Usage:
 		KeyParameter2 = "myparameter2"
 	)
 
-2. Create a concrete parameter struct and define the validation functions:
+2. Define parameters as proto message and define the validation functions:
 
-	type MyParams struct {
-		MyParam1 int64 `json:"my_param1" yaml:"my_param1"`
-		MyParam2 bool `json:"my_param2" yaml:"my_param2"`
+	message MyParams {
+		int64 my_param1 = 1;
+		bool my_param2 = 2;
 	}
 
 	func validateMyParam1(i interface{}) error {
@@ -56,12 +55,12 @@ Basic Usage:
 
 	func (p *MyParams) ParamSetPairs() params.ParamSetPairs {
 		return params.ParamSetPairs{
-			{KeyParameter1, &p.MyParam1, validateMyParam1},
-			{KeyParameter2, &p.MyParam2, validateMyParam2},
+			params.NewParamSetPair(KeyParameter1, &p.MyParam1, validateMyParam1),
+			params.NewParamSetPair(KeyParameter2, &p.MyParam2, validateMyParam2),
 		}
 	}
 
-	func paramKeyTable() params.KeyTable {
+	func ParamKeyTable() params.KeyTable {
 		return params.NewKeyTable().RegisterParamSet(&MyParams{})
 	}
 
@@ -70,7 +69,7 @@ Basic Usage:
 	func NewKeeper(..., paramSpace params.Subspace, ...) Keeper {
 		// set KeyTable if it has not already been set
 		if !paramSpace.HasKeyTable() {
-			paramSpace = paramSpace.WithKeyTable(paramKeyTable())
+			paramSpace = paramSpace.WithKeyTable(ParamKeyTable())
 		}
 
 		return Keeper {

x/params/spec/01_keeper.md

@@ -4,24 +4,16 @@ order: 1
 
 # Keeper
 
-In the app initialization stage, `Keeper.Subspace(Paramspace)` is passed to the 
-user modules, and the subspaces are stored in `Keeper.spaces`. Later it can be 
-retrieved with `Keeper.GetSubspace`, so the keepers holding `Keeper` can access 
-to any subspace. For example, Gov module can take `Keeper` as its argument and 
-modify parameter of any subspace when a `ParameterChangeProposal` is accepted.
+In the app initialization stage, [subspaces](02_subspace.md) can be allocated for other modules' keeper using `Keeper.Subspace` and are stored in `Keeper.spaces`. Then, those modules can have a reference to their specific parameter store through `Keeper.GetSubspace`.
 
 Example:
 
 ```go
-type MasterKeeper struct {
-	pk params.Keeper
+type ExampleKeeper struct {
+	paramSpace paramtypes.Subspace
 }
 
-func (k MasterKeeper) SetParam(ctx sdk.Context, space string, key string, param interface{}) {
-	space, ok := k.ps.GetSubspace(space)
-	if !ok {
-		return
-	}
-	space.Set(ctx, key, param)
+func (k ExampleKeeper) SetParams(ctx sdk.Context, params types.Params) {
+	k.paramSpace.SetParamSet(ctx, &params)
 }
 ```

x/params/spec/02_subspace.md

@@ -4,8 +4,8 @@ order: 2
 
 # Subspace
 
-`Subspace` is a prefixed subspace of the parameter store. Each module who use the 
-parameter store will take a `Subspace`, not the `Keeper`, to isolate permission to access. 
+`Subspace` is a prefixed subspace of the parameter store. Each module which uses the 
+parameter store will take a `Subspace` to isolate permission to access.
 
 ## Key
 
@@ -21,20 +21,18 @@ Subkeys can be used for grouping or dynamic parameter key generation during runt
 All of the parameter keys that will be used should be registered at the compile 
 time. `KeyTable` is essentially a `map[string]attribute`, where the `string` is a parameter key.
 
-Currently, `attribute` only consists of `reflect.Type`, which indicates the parameter 
-type. It is needed even if the state machine has no error, because the paraeter 
-can be modified externally, for example via the governance.
+Currently, `attribute` consists of a `reflect.Type`, which indicates the parameter 
+type to check that provided key and value are compatible and registered, as well as a function `ValueValidatorFn` to validate values.
 
 Only primary keys have to be registered on the `KeyTable`. Subkeys inherit the 
 attribute of the primary key.
 
 ## ParamSet
 
-Modules often define a struct of parameters. Instead of calling methods with 
-each of those parameters, when the struct implements `ParamSet`, it can be used 
-with the following methods:
+Modules often define parameters as a proto message. The generated struct can implement
+`ParamSet` interface to be used with the following methods:
 
 * `KeyTable.RegisterParamSet()`: registers all parameters in the struct
 * `Subspace.{Get, Set}ParamSet()`: Get to & Set from the struct
 
-The implementor should be a pointer in order to use `GetParamSet()`
+The implementor should be a pointer in order to use `GetParamSet()`.

x/params/spec/README.md

@@ -15,9 +15,8 @@ There are two main types, Keeper and Subspace. Subspace is an isolated namespace
 paramstore, where keys are prefixed by preconfigured spacename. Keeper has a
 permission to access all existing spaces.
 
-Subspace can be used by the individual keepers, who needs a private parameter store
-that the other keeper cannot modify. Keeper can be used by the Governance keeper,
-who need to modify any parameter in case of the proposal passes.
+Subspace can be used by the individual keepers, which need a private parameter store
+that the other keepers cannot modify. The params Keeper can be used to add a route to `x/gov` router in order to modify any parameter in case a proposal passes.
 
 The following contents explains how to use params module for master and user modules.