docs: document ConsensusParams (#5165)

Closes #2836

docs/tendermint-core/using-tendermint.md

@@ -47,11 +47,30 @@ definition](https://github.com/tendermint/tendermint/blob/master/types/genesis.g
 - `chain_id`: ID of the blockchain. **This must be unique for
   every blockchain.** If your testnet blockchains do not have unique
   chain IDs, you will have a bad time. The ChainID must be less than 50 symbols.
-- `consensus_params`
+- `consensus_params` [spec](https://github.com/tendermint/spec/blob/master/spec/core/state.md#consensusparams)
   - `block`
+    - `max_bytes`: Max block size, in bytes.
+    - `max_gas`: Max gas per block.
     - `time_iota_ms`: Minimum time increment between consecutive blocks (in
       milliseconds). If the block header timestamp is ahead of the system clock,
       decrease this value.
+  - `evidence`
+    - `max_age_num_blocks`: Max age of evidence, in blocks. The basic formula
+      for calculating this is: MaxAgeDuration / {average block time}.
+    - `max_age_duration`: Max age of evidence, in time. It should correspond
+      with an app's "unbonding period" or other similar mechanism for handling
+      [Nothing-At-Stake
+      attacks](https://github.com/ethereum/wiki/wiki/Proof-of-Stake-FAQ#what-is-the-nothing-at-stake-problem-and-how-can-it-be-fixed).
+    - `max_num`: This sets the maximum number of evidence that can be committed
+      in a single block. and should fall comfortably under the max block
+      bytes when we consider the size of each evidence.
+    - `proof_trial_period`: Proof trial period dictates the time given for
+      nodes accused of amnesia evidence, incorrectly voting twice in two
+      different rounds to respond with their respective proofs.
+  - `validator`
+    - `pub_key_types`: Public key types validators can use.
+  - `version`
+    - `app_version`: ABCI application version.
 - `validators`: List of initial validators. Note this may be overridden entirely by the
   application, and may be left empty to make explicit that the
   application will initialize the validator set with ResponseInitChain.

proto/tendermint/types/params.pb.go

@@ -99,11 +99,15 @@ func (m *ConsensusParams) GetVersion() VersionParams {
 
 // BlockParams contains limits on the block size.
 type BlockParams struct {
+	// Max block size, in bytes.
 	// Note: must be greater than 0
 	MaxBytes int64 `protobuf:"varint,1,opt,name=max_bytes,json=maxBytes,proto3" json:"max_bytes,omitempty"`
+	// Max gas per block.
 	// Note: must be greater or equal to -1
 	MaxGas int64 `protobuf:"varint,2,opt,name=max_gas,json=maxGas,proto3" json:"max_gas,omitempty"`
-	// Minimum time increment between consecutive blocks (in milliseconds)
+	// Minimum time increment between consecutive blocks (in milliseconds) If the
+	// block header timestamp is ahead of the system clock, decrease this value.
+	//
 	// Not exposed to the application.
 	TimeIotaMs int64 `protobuf:"varint,3,opt,name=time_iota_ms,json=timeIotaMs,proto3" json:"time_iota_ms,omitempty"`
 }
@@ -339,8 +343,8 @@ func (m *VersionParams) GetAppVersion() uint64 {
 }
 
 // HashedParams is a subset of ConsensusParams.
-// It is amino encoded and hashed into
-// the Header.ConsensusHash.
+//
+// It is hashed into the Header.ConsensusHash.
 type HashedParams struct {
 	BlockMaxBytes int64 `protobuf:"varint,1,opt,name=block_max_bytes,json=blockMaxBytes,proto3" json:"block_max_bytes,omitempty"`
 	BlockMaxGas   int64 `protobuf:"varint,2,opt,name=block_max_gas,json=blockMaxGas,proto3" json:"block_max_gas,omitempty"`

proto/tendermint/types/params.proto

@@ -19,11 +19,15 @@ message ConsensusParams {
 
 // BlockParams contains limits on the block size.
 message BlockParams {
+  // Max block size, in bytes.
   // Note: must be greater than 0
   int64 max_bytes = 1;
+  // Max gas per block.
   // Note: must be greater or equal to -1
   int64 max_gas = 2;
-  // Minimum time increment between consecutive blocks (in milliseconds)
+  // Minimum time increment between consecutive blocks (in milliseconds) If the
+  // block header timestamp is ahead of the system clock, decrease this value.
+  //
   // Not exposed to the application.
   int64 time_iota_ms = 3;
 }
@@ -74,8 +78,8 @@ message VersionParams {
 }
 
 // HashedParams is a subset of ConsensusParams.
-// It is amino encoded and hashed into
-// the Header.ConsensusHash.
+//
+// It is hashed into the Header.ConsensusHash.
 message HashedParams {
   int64 block_max_bytes = 1;
   int64 block_max_gas   = 2;