Merge PR #5074: move docs/spec into x/module/spec

x/params/spec/01_keeper.md

@@ -0,0 +1,19 @@
+# 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.  
+
+Example:
+
+```go
+type MasterKeeper struct {
+	pk params.Keeper
+}
+
+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)
+}
+```

x/params/spec/02_subspace.md

@@ -0,0 +1,26 @@
+# 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. 
+
+## Key
+
+Parameter keys are human readable alphanumeric strings. A parameter for the key `"ExampleParameter"` is stored under `[]byte("SubspaceName" + "/" + "ExampleParameter")`, where `"SubspaceName"` is the name of the subspace. 
+
+Subkeys are secondary parameter keys those are used along with a primary parameter key. Subkeys can be used for grouping or dynamic parameter key generation during runtime.
+
+## KeyTable
+
+All of the paramter 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.
+
+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:
+
+* `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()`

x/params/spec/README.md

@@ -0,0 +1,23 @@
+# Params module specification
+
+## Abstract
+
+Package params provides a globally available parameter store.
+
+There are two main types, Keeper and Subspace. Subspace is an isolated namespace for a
+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.
+
+The following contents explains how to use params module for master and user modules.
+
+## Contents
+
+1. **[Keeper](01_keeper.md)**
+2. **[Subspace](02_subspace.md)**
+    - [Key](02_subspace.md#key)
+    - [KeyTable](02_subspace.md#keytable)
+    - [ParamSet](02_subspace.md#paramset)