From 4df643271da01950ad3466b3e9b4b8f36175d341 Mon Sep 17 00:00:00 2001
From: Andronik <write@reusable.software>
Date: Tue, 27 Sep 2022 10:48:49 +0200
Subject: [PATCH] make spellcheck green again (#6059)
* make spellcheck green again
* remove the comment
* Fix a comment in `provisioner`
Co-authored-by: Tsvetomir Dimitrov <tsvetomir@parity.io>
---
.../node/core/provisioner/src/disputes/mod.rs | 4 +-
.../src/disputes/prioritized_selection/mod.rs | 22 +++-----
.../src/disputes/random_selection/mod.rs | 2 +-
.../node/primitives/src/disputes/status.rs | 2 +-
polkadot/node/subsystem-types/src/messages.rs | 2 +-
polkadot/primitives/src/runtime_api.rs | 56 +++++++++----------
.../parachains/src/runtime_api_impl/mod.rs | 16 +++---
7 files changed, 49 insertions(+), 55 deletions(-)
diff --git a/polkadot/node/core/provisioner/src/disputes/mod.rs b/polkadot/node/core/provisioner/src/disputes/mod.rs
index 404e800702b..bd19e101bb2 100644
--- a/polkadot/node/core/provisioner/src/disputes/mod.rs
+++ b/polkadot/node/core/provisioner/src/disputes/mod.rs
@@ -17,8 +17,8 @@
//! The disputes module is responsible for selecting dispute votes to be sent with the inherent data. It contains two
//! different implementations, extracted in two separate modules - `random_selection` and `prioritized_selection`. Which
//! implementation will be executed depends on the version of the runtime. Runtime v2 supports `random_selection`. Runtime
-//! v3 and above - `prioritized_selection`. The entrypoint to these implementations is the `select_disputes` function.
-//! prioritized_selection` is considered superior and will be the default one in the future. Refer to the documentation of
+//! `v3` and above - `prioritized_selection`. The entrypoint to these implementations is the `select_disputes` function.
+//! `prioritized_selection` is considered superior and will be the default one in the future. Refer to the documentation of
//! the modules for more details about each implementation.
use crate::LOG_TARGET;
diff --git a/polkadot/node/core/provisioner/src/disputes/prioritized_selection/mod.rs b/polkadot/node/core/provisioner/src/disputes/prioritized_selection/mod.rs
index 6582f0a612f..07426ef1a75 100644
--- a/polkadot/node/core/provisioner/src/disputes/prioritized_selection/mod.rs
+++ b/polkadot/node/core/provisioner/src/disputes/prioritized_selection/mod.rs
@@ -45,23 +45,17 @@ pub const MAX_DISPUTE_VOTES_FORWARDED_TO_RUNTIME: usize = 200_000;
#[cfg(test)]
pub const MAX_DISPUTE_VOTES_FORWARDED_TO_RUNTIME: usize = 200;
-/// Controls how much dispute votes to be fetched from the runtime per iteration in `fn vote_selection`.
-/// The purpose is to fetch the votes in batches until `MAX_DISPUTE_VOTES_FORWARDED_TO_RUNTIME` is
-/// reached. This value should definitely be less than `MAX_DISPUTE_VOTES_FORWARDED_TO_RUNTIME`.
+/// Controls how much dispute votes to be fetched from the `dispute-coordinator` per iteration in
+/// `fn vote_selection`. The purpose is to fetch the votes in batches until
+/// `MAX_DISPUTE_VOTES_FORWARDED_TO_RUNTIME` is reached. If all votes are fetched in single call
+/// we might fetch votes which we never use. This will create unnecessary load on `dispute-coordinator`.
///
-/// The ratio `MAX_DISPUTE_VOTES_FORWARDED_TO_RUNTIME` / `VOTES_SELECTION_BATCH_SIZE` gives an
-/// approximation about how many runtime requests will be issued to fetch votes from the runtime in
-/// a single `select_disputes` call. Ideally we don't want to make more than 2-3 calls. In practice
-/// it's hard to predict this number because we can't guess how many new votes (for the runtime) a
-/// batch will contain.
-///
-/// The value below is reached by: `MAX_DISPUTE_VOTES_FORWARDED_TO_RUNTIME` / 2 + 10%
-/// The 10% makes approximately means '10% new votes'. Tweak this if provisioner makes excessive
-/// number of runtime calls.
+/// This value should be less than `MAX_DISPUTE_VOTES_FORWARDED_TO_RUNTIME`. Increase it in case
+/// `provisioner` sends too many `QueryCandidateVotes` messages to `dispite-coordinator`.
#[cfg(not(test))]
const VOTES_SELECTION_BATCH_SIZE: usize = 1_100;
#[cfg(test)]
-const VOTES_SELECTION_BATCH_SIZE: usize = 11; // Just a small value for tests. Doesn't follow the rules above
+const VOTES_SELECTION_BATCH_SIZE: usize = 11;
/// Implements the `select_disputes` function which selects dispute votes which should
/// be sent to the Runtime.
@@ -89,7 +83,7 @@ const VOTES_SELECTION_BATCH_SIZE: usize = 11; // Just a small value for tests. D
///
/// The logic outlined above relies on `RuntimeApiRequest::Disputes` message from the Runtime. The user
/// check the Runtime version before calling `select_disputes`. If the function is used with old runtime
-/// an error is logged and the logic will continue with empty onchain votes HashMap.
+/// an error is logged and the logic will continue with empty onchain votes `HashMap`.
pub async fn select_disputes<Sender>(
sender: &mut Sender,
metrics: &metrics::Metrics,
diff --git a/polkadot/node/core/provisioner/src/disputes/random_selection/mod.rs b/polkadot/node/core/provisioner/src/disputes/random_selection/mod.rs
index 7af025700ba..a25d3445ac6 100644
--- a/polkadot/node/core/provisioner/src/disputes/random_selection/mod.rs
+++ b/polkadot/node/core/provisioner/src/disputes/random_selection/mod.rs
@@ -15,7 +15,7 @@
// along with Polkadot. If not, see <http://www.gnu.org/licenses/>.
//! This module selects all RECENT disputes, fetches the votes for them from dispute-coordinator and
-//! returns them as MultiDisputeStatementSet. If the RECENT disputes are more than
+//! returns them as `MultiDisputeStatementSet`. If the RECENT disputes are more than
//! `MAX_DISPUTES_FORWARDED_TO_RUNTIME` constant - the ACTIVE disputes plus a random selection of
//! RECENT disputes (up to `MAX_DISPUTES_FORWARDED_TO_RUNTIME`) are returned instead.
//! If the ACTIVE disputes are also above `MAX_DISPUTES_FORWARDED_TO_RUNTIME` limit - a random selection
diff --git a/polkadot/node/primitives/src/disputes/status.rs b/polkadot/node/primitives/src/disputes/status.rs
index 44aed9b78e2..c0ffb907423 100644
--- a/polkadot/node/primitives/src/disputes/status.rs
+++ b/polkadot/node/primitives/src/disputes/status.rs
@@ -117,7 +117,7 @@ impl DisputeStatus {
/// disputes.
pub const ACTIVE_DURATION_SECS: Timestamp = 180;
-/// Returns true if the dispute has concluded for longer than ACTIVE_DURATION_SECS
+/// Returns true if the dispute has concluded for longer than [`ACTIVE_DURATION_SECS`].
pub fn dispute_is_inactive(status: &DisputeStatus, now: &Timestamp) -> bool {
let at = status.concluded_at();
diff --git a/polkadot/node/subsystem-types/src/messages.rs b/polkadot/node/subsystem-types/src/messages.rs
index c37f773b383..17b47e507c2 100644
--- a/polkadot/node/subsystem-types/src/messages.rs
+++ b/polkadot/node/subsystem-types/src/messages.rs
@@ -699,7 +699,7 @@ pub enum RuntimeApiRequest {
OccupiedCoreAssumption,
RuntimeApiSender<Option<ValidationCodeHash>>,
),
- /// Returns all on-chain disputes at given block number. Available in v3.
+ /// Returns all on-chain disputes at given block number. Available in `v3`.
Disputes(RuntimeApiSender<Vec<(SessionIndex, CandidateHash, DisputeState<BlockNumber>)>>),
}
diff --git a/polkadot/primitives/src/runtime_api.rs b/polkadot/primitives/src/runtime_api.rs
index d0d0b7220bb..2f6793d2203 100644
--- a/polkadot/primitives/src/runtime_api.rs
+++ b/polkadot/primitives/src/runtime_api.rs
@@ -21,18 +21,18 @@
//! (which is versioned) or they can be staging (aka unstable/testing
//! functions).
//!
-//! The separation outlined above is achieved with the versioned api feature
+//! The separation outlined above is achieved with the versioned API feature
//! of `decl_runtime_apis!` and `impl_runtime_apis!`. Before moving on let's
-//! see a quick example about how api versioning works.
+//! see a quick example about how API versioning works.
//!
-//! # Runtime api versioning crash course
+//! # Runtime API versioning crash course
//!
//! The versioning is achieved with the `api_version` attribute. It can be
//! placed on:
-//! * trait declaration - represents the base version of the api.
+//! * trait declaration - represents the base version of the API.
//! * method declaration (inside a trait declaration) - represents a versioned
//! method, which is not available in the base version.
-//! * trait implementation - represents which version of the api is being
+//! * trait implementation - represents which version of the API is being
//! implemented.
//!
//! Let's see a quick example:
@@ -61,53 +61,53 @@
//! }
//! }
//! ```
-//! A new api named `MyApi` is declared with `decl_runtime_apis!`. The trait declaration
+//! A new API named `MyApi` is declared with `decl_runtime_apis!`. The trait declaration
//! has got an `api_version` attribute which represents its base version - 2 in this case.
//!
-//! The api has got three methods - `fn1`, `fn2`, `fn3` and `fn4`. `fn3` and `fn4` has got
+//! The API has got three methods - `fn1`, `fn2`, `fn3` and `fn4`. `fn3` and `fn4` has got
//! an `api_version` attribute which makes them versioned methods. These methods do not exist
-//! in the base version of the api. Behind the scenes the declaration above creates three
-//! runtime apis:
-//! * MyApiV2 with `fn1` and `fn2`
-//! * MyApiV3 with `fn1`, `fn2` and `fn3`.
-//! * MyApiV4 with `fn1`, `fn2`, `fn3` and `fn4`.
+//! in the base version of the API. Behind the scenes the declaration above creates three
+//! runtime APIs:
+//! * `MyApiV2` with `fn1` and `fn2`
+//! * `MyApiV3` with `fn1`, `fn2` and `fn3`.
+//! * `MyApiV4` with `fn1`, `fn2`, `fn3` and `fn4`.
//!
-//! Please note that v4 contains all methods from v3, v3 all methods from v2 and so on.
+//! Please note that `v4` contains all methods from `v3`, `v3` all methods from `v2` and so on.
//!
-//! Back to our example. At the end runtime api is implemented for `struct Runtime` with
-//! `impl_runtime_apis` macro. `api_version` attribute is attached to the impl block which
+//! Back to our example. At the end runtime API is implemented for `struct Runtime` with
+//! `impl_runtime_apis` macro. `api_version` attribute is attached to the `impl` block which
//! means that a version different from the base one is being implemented - in our case this
-//! is v3.
+//! is `v3`.
//!
-//! This version of the api contains three methods so the `impl` block has got definitions
-//! for them. Note that `fn4` is not implemented as it is not part of this version of the api.
+//! This version of the API contains three methods so the `impl` block has got definitions
+//! for them. Note that `fn4` is not implemented as it is not part of this version of the API.
//! `impl_runtime_apis` generates a default implementation for it calling `unimplemented!()`.
//!
//! Hopefully this should be all you need to know in order to use versioned methods in the node.
-//! For more details about how the api versioning works refer to `spi_api`
+//! For more details about how the API versioning works refer to `spi_api`
//! documentation [here](https://docs.substrate.io/rustdocs/latest/sp_api/macro.decl_runtime_apis.html).
//!
//! # How versioned methods are used for `ParachainHost`
//!
-//! Let's introduce two types of `ParachainHost` api implementation:
+//! Let's introduce two types of `ParachainHost` API implementation:
//! * stable - used on stable production networks like Polkadot and Kusama. There is only one
-//! stable api at a single point in time.
+//! stable API at a single point in time.
//! * staging - used on test networks like Westend or Rococo. Depending on the development needs
-//! there can be zero, one or multiple staging apis.
+//! there can be zero, one or multiple staging APIs.
//!
-//! The stable version of `ParachainHost` is indicated by the base version of the api. Any staging
+//! The stable version of `ParachainHost` is indicated by the base version of the API. Any staging
//! method must use `api_version` attribute so that it is assigned to a specific version of a
-//! staging api. This way in a single declaration one can see what's the stable version of
+//! staging API. This way in a single declaration one can see what's the stable version of
//! `ParachainHost` and what staging versions/functions are available.
//!
-//! All stable api functions should use primitives from the latest version.
-//! In the time of writing of this document - this is v2. So for example:
+//! All stable API functions should use primitives from the latest version.
+//! In the time of writing of this document - this is `v2`. So for example:
//! ```ignore
//! fn validators() -> Vec<v2::ValidatorId>;
//! ```
-//! indicates a function from the stable v2 API.
+//! indicates a function from the stable `v2` API.
//!
-//! All staging api functions should use primitives from vstaging. They should be clearly separated
+//! All staging API functions should use primitives from `vstaging`. They should be clearly separated
//! from the stable primitives.
use crate::v2;
diff --git a/polkadot/runtime/parachains/src/runtime_api_impl/mod.rs b/polkadot/runtime/parachains/src/runtime_api_impl/mod.rs
index c045b474786..da1cd6d0933 100644
--- a/polkadot/runtime/parachains/src/runtime_api_impl/mod.rs
+++ b/polkadot/runtime/parachains/src/runtime_api_impl/mod.rs
@@ -17,14 +17,14 @@
//! Runtime API implementations for Parachains.
//!
//! These are exposed as different modules using different sets of primitives.
-//! At the moment there is a v2 module for the current stable api and
-//! vstaging module for all staging methods.
-//! When new version of the stable api is released it will be based on v2 and
-//! will contain methods from vstaging.
+//! At the moment there is a `v2` module for the current stable API and
+//! `vstaging` module for all staging methods.
+//! When new version of the stable API is released it will be based on `v2` and
+//! will contain methods from `vstaging`.
//! The promotion consists of the following steps:
-//! 1. Bump the version of the stable module (e.g. v2 becomes v3)
-//! 2. Move methods from vstaging to v3. The new stable version should include
-//! all methods from vstaging tagged with the new version number (e.g. all
-//! v3 methods).
+//! 1. Bump the version of the stable module (e.g. `v2` becomes `v3`)
+//! 2. Move methods from `vstaging` to `v3`. The new stable version should include
+//! all methods from `vstaging` tagged with the new version number (e.g. all
+//! `v3` methods).
pub mod v2;
pub mod vstaging;
--
GitLab