chore: adjust comments mannuly

nervosnetwork · Dec 30, 2020 · 21b6367 · 21b6367
1 parent 2c39c0a
commit 21b6367
Show file tree

Hide file tree

Showing 20 changed files with 97 additions and 136 deletions.
diff --git a/chain/src/tests/basic.rs b/chain/src/tests/basic.rs
@@ -811,9 +811,13 @@ fn test_next_epoch_ext() {
         // upper bound trigger
         assert_eq!(epoch.length(), 800, "epoch length {}", epoch.length());
 
-        // orphan_rate_estimation = 1 / ( (1 + o_i ) * L_ideal * C_i,m / (o_i * L_i * C_i+1,m) − 1)
-        // = 133 / 9587 Diff_i+1 = (HPS_i · L_ideal) / (1 + orphan_rate_estimation ) *
-        // C_i+1,m 50 * 14400 * 9587 / ((133 + 9587) * 800)
+        // orphan_rate_estimation
+        //   = 1 / ( (1 + o_i ) * L_ideal * C_i,m / (o_i * L_i * C_i+1,m) − 1)
+        //   = 133 / 9587
+        //
+        // Diff_i+1 = (HPS_i · L_ideal) / (1 + orphan_rate_estimation ) * C_i+1,m
+        //
+        // 50 * 14400 * 9587 / ((133 + 9587) * 800)
         assert_eq!(
             epoch.compact_target(),
             difficulty_to_compact(U256::from(887u64)), // 887

diff --git a/network/src/services/dns_seeding/seed_record.rs b/network/src/services/dns_seeding/seed_record.rs
@@ -40,8 +40,7 @@ const SEP: char = ';';
 
 // Typical txt record:
 // ==================
-//   47.103.65.40;49582;QmbU82jmDbu8AsUfa6bDKPHxTpwnPfcRQrzNPacKcSyM1Y;1574942409;
-// K1vAkHZZ8to5VmjD4eyv65ENLbNa9Tda4Aytd8DE9iipFQanRpcZtSPyRiiGHThRGJPVRD18KAsGb8kV2s2WBK39R
+// 47.103.65.40;49582;QmbU82jmDbu8AsUfa6bDKPHxTpwnPfcRQrzNPacKcSyM1Y;1574942409;K1vAkHZZ8to5VmjD4eyv65ENLbNa9Tda4Aytd8DE9iipFQanRpcZtSPyRiiGHThRGJPVRD18KAsGb8kV2s2WBK39R
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct SeedRecord {
     ip: IpAddr,

diff --git a/rpc/src/module/alert.rs b/rpc/src/module/alert.rs
@@ -23,13 +23,9 @@ pub trait AlertRpc {
     ///
     /// ## Errors
     ///
-    /// * [`AlertFailedToVerifySignatures
-    ///   (-1000)`](../enum.RPCError.html#variant.AlertFailedToVerifySignatures) - Some signatures
-    ///   in the request are invalid.
-    /// * [`P2PFailedToBroadcast (-101)`](../enum.RPCError.html#variant.P2PFailedToBroadcast) -
-    ///   Alert is saved locally but has failed to broadcast to the P2P network.
-    /// * `InvalidParams (-32602)` - The time specified in `alert.notice_until` must be in the
-    ///   future.
+    /// * [`AlertFailedToVerifySignatures (-1000)`](../enum.RPCError.html#variant.AlertFailedToVerifySignatures) - Some signatures in the request are invalid.
+    /// * [`P2PFailedToBroadcast (-101)`](../enum.RPCError.html#variant.P2PFailedToBroadcast) - Alert is saved locally but has failed to broadcast to the P2P network.
+    /// * `InvalidParams (-32602)` - The time specified in `alert.notice_until` must be in the future.
     ///
     /// ## Examples
     ///

diff --git a/rpc/src/module/chain.rs b/rpc/src/module/chain.rs
@@ -183,12 +183,8 @@ pub trait ChainRpc {
     ///
     /// ## Errors
     ///
-    /// * [`ChainIndexIsInconsistent
-    ///   (-201)`](../enum.RPCError.html#variant.ChainIndexIsInconsistent) - The index is
-    ///   inconsistent. It says a block hash is in the main chain, but cannot read it from the
-    ///   database.
-    /// * [`DatabaseIsCorrupt (-202)`](../enum.RPCError.html#variant.DatabaseIsCorrupt) - The data
-    ///   read from database is dirty. Please report it as a bug.
+    /// * [`ChainIndexIsInconsistent (-201)`](../enum.RPCError.html#variant.ChainIndexIsInconsistent) - The index is inconsistent. It says a block hash is in the main chain, but cannot read it from the database.
+    /// * [`DatabaseIsCorrupt (-202)`](../enum.RPCError.html#variant.DatabaseIsCorrupt) - The data read from database is dirty. Please report it as a bug.
     ///
     /// ## Examples
     ///
@@ -385,10 +381,7 @@ pub trait ChainRpc {
     ///
     /// ## Errors
     ///
-    /// * [`ChainIndexIsInconsistent
-    ///   (-201)`](../enum.RPCError.html#variant.ChainIndexIsInconsistent) - The index is
-    ///   inconsistent. It says a block hash is in the main chain, but cannot read it from the
-    ///   database.
+    /// * [`ChainIndexIsInconsistent (-201)`](../enum.RPCError.html#variant.ChainIndexIsInconsistent) - The index is inconsistent. It says a block hash is in the main chain, but cannot read it from the database.
     ///
     /// ## Examples
     ///

diff --git a/rpc/src/module/experiment.rs b/rpc/src/module/experiment.rs
@@ -143,12 +143,8 @@ pub trait ExperimentRpc {
     ///
     /// ## Errors
     ///
-    /// * [`TransactionFailedToResolve
-    ///   (-301)`](../enum.RPCError.html#variant.TransactionFailedToResolve) - Failed to resolve the
-    ///   referenced cells and headers used in the transaction, as inputs or dependencies.
-    /// * [`TransactionFailedToVerify
-    ///   (-302)`](../enum.RPCError.html#variant.TransactionFailedToVerify) - There is a script
-    ///   returns with an error.
+    /// * [`TransactionFailedToResolve (-301)`](../enum.RPCError.html#variant.TransactionFailedToResolve) - Failed to resolve the referenced cells and headers used in the transaction, as inputs or dependencies.
+    /// * [`TransactionFailedToVerify (-302)`](../enum.RPCError.html#variant.TransactionFailedToVerify) - There is a script returns with an error.
     ///
     /// ## Examples
     ///
@@ -237,10 +233,8 @@ pub trait ExperimentRpc {
     ///
     /// ## Errors
     ///
-    /// * [`DaoError (-5)`](../enum.RPCError.html#variant.DaoError) - The given out point is not a
-    ///   valid cell for DAO computation.
-    /// * [`CKBInternalError (-1)`](../enum.RPCError.html#variant.CKBInternalError) - Mathematics
-    ///   overflow.
+    /// * [`DaoError (-5)`](../enum.RPCError.html#variant.DaoError) - The given out point is not a valid cell for DAO computation.
+    /// * [`CKBInternalError (-1)`](../enum.RPCError.html#variant.CKBInternalError) - Mathematics overflow.
     ///
     /// ## Examples
     ///

diff --git a/rpc/src/module/pool.rs b/rpc/src/module/pool.rs
@@ -27,33 +27,14 @@ pub trait PoolRpc {
     ///
     /// ## Errors
     ///
-    /// * [`PoolRejectedTransactionByOutputsValidator
-    ///   (-1102)`](../enum.RPCError.html#variant.PoolRejectedTransactionByOutputsValidator) - The
-    ///   transaction is rejected by the validator specified by `outputs_validator`. If you really
-    ///   want to send transactions with advanced scripts, please set `outputs_validator` to
-    ///   "passthrough".
-    /// * [`PoolRejectedTransactionByIllTransactionChecker
-    ///   (-1103)`](../enum.RPCError.html#variant.PoolRejectedTransactionByIllTransactionChecker) -
-    ///   Pool rejects some transactions which seem contain invalid VM instructions. See the issue
-    ///   link in the error message for details.
-    /// * [`PoolRejectedTransactionByMinFeeRate
-    ///   (-1104)`](../enum.RPCError.html#variant.PoolRejectedTransactionByMinFeeRate) - The
-    ///   transaction fee rate must be greater than or equal to the config option
-    ///   `tx_pool.min_fee_rate`.
-    /// * [`PoolRejectedTransactionByMaxAncestorsCountLimit
-    ///   (-1105)`](../enum.RPCError.html#variant.PoolRejectedTransactionByMaxAncestorsCountLimit) -
-    ///   The ancestors count must be greater than or equal to the config option
-    ///   `tx_pool.max_ancestors_count`.
+    /// * [`PoolRejectedTransactionByOutputsValidator (-1102)`](../enum.RPCError.html#variant.PoolRejectedTransactionByOutputsValidator) - The transaction is rejected by the validator specified by `outputs_validator`. If you really want to send transactions with advanced scripts, please set `outputs_validator` to "passthrough".
+    /// * [`PoolRejectedTransactionByIllTransactionChecker (-1103)`](../enum.RPCError.html#variant.PoolRejectedTransactionByIllTransactionChecker) - Pool rejects some transactions which seem contain invalid VM instructions. See the issue link in the error message for details.
+    /// * [`PoolRejectedTransactionByMinFeeRate (-1104)`](../enum.RPCError.html#variant.PoolRejectedTransactionByMinFeeRate) - The transaction fee rate must be greater than or equal to the config option `tx_pool.min_fee_rate`.
+    /// * [`PoolRejectedTransactionByMaxAncestorsCountLimit (-1105)`](../enum.RPCError.html#variant.PoolRejectedTransactionByMaxAncestorsCountLimit) - The ancestors count must be greater than or equal to the config option `tx_pool.max_ancestors_count`.
     /// * [`PoolIsFull (-1106)`](../enum.RPCError.html#variant.PoolIsFull) - Pool is full.
-    /// * [`PoolRejectedDuplicatedTransaction
-    ///   (-1107)`](../enum.RPCError.html#variant.PoolRejectedDuplicatedTransaction) - The
-    ///   transaction is already in the pool.
-    /// * [`TransactionFailedToResolve
-    ///   (-301)`](../enum.RPCError.html#variant.TransactionFailedToResolve) - Failed to resolve the
-    ///   referenced cells and headers used in the transaction, as inputs or dependencies.
-    /// * [`TransactionFailedToVerify
-    ///   (-302)`](../enum.RPCError.html#variant.TransactionFailedToVerify) - Failed to verify the
-    ///   transaction.
+    /// * [`PoolRejectedDuplicatedTransaction (-1107)`](../enum.RPCError.html#variant.PoolRejectedDuplicatedTransaction) - The transaction is already in the pool.
+    /// * [`TransactionFailedToResolve (-301)`](../enum.RPCError.html#variant.TransactionFailedToResolve) - Failed to resolve the referenced cells and headers used in the transaction, as inputs or dependencies.
+    /// * [`TransactionFailedToVerify (-302)`](../enum.RPCError.html#variant.TransactionFailedToVerify) - Failed to verify the transaction.
     ///
     /// ## Examples
     ///

diff --git a/rpc/src/test.rs b/rpc/src/test.rs
@@ -667,7 +667,7 @@ where
     *response = example.response.clone()
 }
 
-// 
+//
 // * Use replace_rpc_response to skip the response matching assertions.
 // * Fix timestamp related fields.
 fn mock_rpc_response(example: &RpcTestExample, response: &mut RpcTestResponse) {

diff --git a/script/src/verify.rs b/script/src/verify.rs
@@ -469,9 +469,13 @@ mod tests {
 
     // NOTE: `verify` binary is outdated and most related unit tests are testing `script` crate
     // functions I try to keep unit test code unmodified as much as possible, and may add it
-    // back in future PR. fn open_cell_verify() -> File {
-    //     File::open(Path::new(env!("CARGO_MANIFEST_DIR")).join("../script/testdata/verify")).
-    // unwrap() }
+    // back in future PR.
+    //
+    // ```ignore
+    // fn open_cell_verify() -> File {
+    //     File::open(Path::new(env!("CARGO_MANIFEST_DIR")).join("../script/testdata/verify")).unwrap()
+    // }
+    // ```
 
     fn open_cell_always_success() -> File {
         File::open(Path::new(env!("CARGO_MANIFEST_DIR")).join("../script/testdata/always_success"))

diff --git a/spec/src/consensus.rs b/spec/src/consensus.rs
@@ -96,8 +96,11 @@ pub const TYPE_ID_CODE_HASH: H256 = h256!("0x545950455f4944");
 /// and commitment.
 ///
 /// A non-cellbase transaction is committed at height h_c if all of the following conditions are
-/// met: 1) it is proposed at height h_p of the same chain, where w_close <= h_c − h_p <= w_far ;
-/// 2) it is in the commitment zone of the main chain block with height h_c ;
+/// met:
+///
+/// 1. it is proposed at height h_p of the same chain, where w_close <= h_c − h_p <= w_far ;
+///
+/// 2. it is in the commitment zone of the main chain block with height h_c ;
 ///
 ///   ```text
 ///   ProposalWindow (2, 10)

diff --git a/spec/src/lib.rs b/spec/src/lib.rs
@@ -86,24 +86,21 @@ pub mod default_params {
 
     /// The default initial_primary_epoch_reward
     ///
-    /// Apply to [`initial_primary_epoch_reward`](../consensus/struct.Consensus.html#structfield.
-    /// initial_primary_epoch_reward)
+    /// Apply to [`initial_primary_epoch_reward`](../consensus/struct.Consensus.html#structfield.initial_primary_epoch_reward)
     pub fn initial_primary_epoch_reward() -> Capacity {
         INITIAL_PRIMARY_EPOCH_REWARD
     }
 
     /// The default secondary_epoch_reward
     ///
-    /// Apply to [`secondary_epoch_reward`](../consensus/struct.Consensus.html#structfield.
-    /// secondary_epoch_reward)
+    /// Apply to [`secondary_epoch_reward`](../consensus/struct.Consensus.html#structfield.secondary_epoch_reward)
     pub fn secondary_epoch_reward() -> Capacity {
         DEFAULT_SECONDARY_EPOCH_REWARD
     }
 
     /// The default max_block_cycles
     ///
-    /// Apply to [`max_block_cycles`](../consensus/struct.Consensus.html#structfield.
-    /// max_block_cycles)
+    /// Apply to [`max_block_cycles`](../consensus/struct.Consensus.html#structfield.max_block_cycles)
     pub fn max_block_cycles() -> Cycle {
         MAX_BLOCK_CYCLES
     }
@@ -117,56 +114,49 @@ pub mod default_params {
 
     /// The default cellbase_maturity
     ///
-    /// Apply to [`cellbase_maturity`](../consensus/struct.Consensus.html#structfield.
-    /// cellbase_maturity)
+    /// Apply to [`cellbase_maturity`](../consensus/struct.Consensus.html#structfield.cellbase_maturity)
     pub fn cellbase_maturity() -> u64 {
         CELLBASE_MATURITY.full_value()
     }
 
     /// The default primary_epoch_reward_halving_interval
     ///
-    /// Apply to [`primary_epoch_reward_halving_interval`](../consensus/struct.Consensus.html#
-    /// structfield.primary_epoch_reward_halving_interval)
+    /// Apply to [`primary_epoch_reward_halving_interval`](../consensus/struct.Consensus.html#structfield.primary_epoch_reward_halving_interval)
     pub fn primary_epoch_reward_halving_interval() -> EpochNumber {
         DEFAULT_PRIMARY_EPOCH_REWARD_HALVING_INTERVAL
     }
 
     /// The default epoch_duration
     ///
-    /// Apply to [`epoch_duration_target`](../consensus/struct.Consensus.html#structfield.
-    /// epoch_duration_target)
+    /// Apply to [`epoch_duration_target`](../consensus/struct.Consensus.html#structfield.epoch_duration_target)
     pub fn epoch_duration_target() -> u64 {
         DEFAULT_EPOCH_DURATION_TARGET
     }
 
     /// The default genesis_epoch_length
     ///
-    /// Apply to [`genesis_epoch_length`](../consensus/struct.Consensus.html#structfield.
-    /// genesis_epoch_length)
+    /// Apply to [`genesis_epoch_length`](../consensus/struct.Consensus.html#structfield.genesis_epoch_length)
     pub fn genesis_epoch_length() -> u64 {
         GENESIS_EPOCH_LENGTH
     }
 
     /// The default max_block_proposals_limit
     ///
-    /// Apply to [`max_block_proposals_limit`](../consensus/struct.Consensus.html#structfield.
-    /// max_block_proposals_limit)
+    /// Apply to [`max_block_proposals_limit`](../consensus/struct.Consensus.html#structfield.max_block_proposals_limit)
     pub fn max_block_proposals_limit() -> u64 {
         MAX_BLOCK_PROPOSALS_LIMIT
     }
 
     /// The default permanent_difficulty_in_dummy
     ///
-    /// Apply to [`permanent_difficulty_in_dummy`](../consensus/struct.Consensus.html#structfield.
-    /// permanent_difficulty_in_dummy)
+    /// Apply to [`permanent_difficulty_in_dummy`](../consensus/struct.Consensus.html#structfield.permanent_difficulty_in_dummy)
     pub fn permanent_difficulty_in_dummy() -> bool {
         false
     }
 
     /// The default orphan_rate_target
     ///
-    /// Apply to [`orphan_rate_target`](../consensus/struct.Consensus.html#structfield.
-    /// orphan_rate_target)
+    /// Apply to [`orphan_rate_target`](../consensus/struct.Consensus.html#structfield.orphan_rate_target)
     pub fn orphan_rate_target() -> (u32, u32) {
         DEFAULT_ORPHAN_RATE_TARGET
     }
@@ -177,14 +167,12 @@ pub mod default_params {
 pub struct Params {
     /// The initial_primary_epoch_reward
     ///
-    /// See [`initial_primary_epoch_reward`](consensus/struct.Consensus.html#structfield.
-    /// initial_primary_epoch_reward)
+    /// See [`initial_primary_epoch_reward`](consensus/struct.Consensus.html#structfield.initial_primary_epoch_reward)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub initial_primary_epoch_reward: Option<Capacity>,
     /// The secondary_epoch_reward
     ///
-    /// See [`secondary_epoch_reward`](consensus/struct.Consensus.html#structfield.
-    /// secondary_epoch_reward)
+    /// See [`secondary_epoch_reward`](consensus/struct.Consensus.html#structfield.secondary_epoch_reward)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub secondary_epoch_reward: Option<Capacity>,
     /// The max_block_cycles
@@ -204,32 +192,27 @@ pub struct Params {
     pub cellbase_maturity: Option<u64>,
     /// The primary_epoch_reward_halving_interval
     ///
-    /// See [`primary_epoch_reward_halving_interval`](consensus/struct.Consensus.html#structfield.
-    /// primary_epoch_reward_halving_interval)
+    /// See [`primary_epoch_reward_halving_interval`](consensus/struct.Consensus.html#structfield.primary_epoch_reward_halving_interval)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub primary_epoch_reward_halving_interval: Option<EpochNumber>,
     /// The epoch_duration_target
     ///
-    /// See [`epoch_duration_target`](consensus/struct.Consensus.html#structfield.
-    /// epoch_duration_target)
+    /// See [`epoch_duration_target`](consensus/struct.Consensus.html#structfield.epoch_duration_target)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub epoch_duration_target: Option<u64>,
     /// The genesis_epoch_length
     ///
-    /// See [`genesis_epoch_length`](consensus/struct.Consensus.html#structfield.
-    /// genesis_epoch_length)
+    /// See [`genesis_epoch_length`](consensus/struct.Consensus.html#structfield.genesis_epoch_length)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub genesis_epoch_length: Option<BlockNumber>,
     /// The permanent_difficulty_in_dummy
     ///
-    /// See [`permanent_difficulty_in_dummy`](consensus/struct.Consensus.html#structfield.
-    /// permanent_difficulty_in_dummy)
+    /// See [`permanent_difficulty_in_dummy`](consensus/struct.Consensus.html#structfield.permanent_difficulty_in_dummy)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub permanent_difficulty_in_dummy: Option<bool>,
     /// The max_block_proposals_limit
     ///
-    /// See [`max_block_proposals_limit`](consensus/struct.Consensus.html#structfield.
-    /// max_block_proposals_limit)
+    /// See [`max_block_proposals_limit`](consensus/struct.Consensus.html#structfield.max_block_proposals_limit)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub max_block_proposals_limit: Option<u64>,
     /// The orphan_rate_target

diff --git a/sync/src/synchronizer/mod.rs b/sync/src/synchronizer/mod.rs
@@ -363,7 +363,7 @@ impl Synchronizer {
     }
 
     /// Regularly check and eject some nodes that do not respond in time
-    // 
+    //
     //   - If at timeout their best known block now has more work than our tip when the timeout was
     //     set, then either reset the timeout or clear it (after comparing against our current tip's
     //     work)

diff --git a/tx-pool/src/block_assembler/mod.rs b/tx-pool/src/block_assembler/mod.rs
@@ -192,10 +192,11 @@ impl BlockAssembler {
     }
 
     // A block B1 is considered to be the uncle of another block B2 if all of the following
-    // conditions are met: (1) they are in the same epoch, sharing the same difficulty;
-    // (2) height(B2) > height(B1);
-    // (3) B1's parent is either B2's ancestor or embedded in B2 or its ancestors as an uncle;
-    // and (4) B2 is the first block in its chain to refer to B1.
+    // conditions are met:
+    //
+    // 1. they are in the same epoch, sharing the same difficulty;
+    // 2. height(B2) > height(B1);
+    // 3. B1's parent is either B2's ancestor or embedded in B2 or its ancestors as an uncle; and (4) B2 is the first block in its chain to refer to B1.
     pub(crate) fn prepare_uncles(
         snapshot: &Snapshot,
         candidate_number: BlockNumber,

diff --git a/util/jsonrpc-types/src/blockchain.rs b/util/jsonrpc-types/src/blockchain.rs
@@ -1182,8 +1182,10 @@ pub struct MerkleProof {
 /// and commitment.
 ///
 /// A non-cellbase transaction is committed at height h_c if all of the following conditions are
-/// met: 1) it is proposed at height h_p of the same chain, where w_close <= h_c − h_p <= w_far ;
-/// 2) it is in the commitment zone of the main chain block with height h_c ;
+/// met:
+///
+/// 1. it is proposed at height h_p of the same chain, where w_close <= h_c − h_p <= w_far ;
+/// 2. it is in the commitment zone of the main chain block with height h_c ;
 ///
 /// ```text
 ///   ProposalWindow { closest: 2, farthest: 10 }

diff --git a/util/proposal-table/src/lib.rs b/util/proposal-table/src/lib.rs
@@ -104,12 +104,15 @@ impl ProposalTable {
 
         ckb_logger::trace!("[proposal_finalize] table {:?}", self.table);
 
-        // 
-        // - if candidate_number <= self.proposal_window.closest() new_ids = [] gap =
-        //   [1..candidate_number]
-        // - else new_ids = [candidate_number- farthest..= candidate_number- closest] gap =
-        //   [candidate_number- closest + 1..candidate_number]
+        // ```
+        // - if candidate_number <= self.proposal_window.closest()
+        //       new_ids = []
+        //       gap = [1..candidate_number]
+        // - else
+        //       new_ids = [candidate_number- farthest..= candidate_number- closest]
+        //       gap = [candidate_number- closest + 1..candidate_number]
         // - end
+        // ```
         let (new_ids, gap) = if candidate_number <= self.proposal_window.closest() {
             (
                 HashSet::new(),