A0-3132: Add pallets documentation to metadata

.github/workflows/_check-code-formatting.yml

@@ -23,4 +23,4 @@ jobs:
           components: rustfmt
 
       - name: Run Format Checks
-        run: cargo +nightly-2023-01-10 fmt --all
+        run: cargo +nightly-2023-01-10 fmt --all --check

pallets/aleph/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pallet-aleph"
-version = "0.5.5"
+version = "0.6.0"
 license = "Apache 2.0"
 authors.workspace = true
 edition.workspace = true

pallets/aleph/README.md

@@ -0,0 +1,19 @@
+# pallet-aleph
+
+This pallet is the runtime companion of the Aleph finality gadget.
+
+Currently, it only provides support for changing sessions but in the future
+it will allow reporting equivocation in AlephBFT.
+
+This pallet relies on an extension of the `AlephSessionApi` Runtime API to handle the finality
+version. The scheduled version change is persisted as `FinalityScheduledVersionChange`. This
+value stores the information about a scheduled finality version change, where `version_incoming`
+is the version to be set and `session` is the session on which the new version will be set.
+A `pallet_session::Session_Manager` checks whether a scheduled version change has moved into
+the past and, if so, records it as the current version represented as `FinalityVersion`,
+and clears `FinalityScheduledVersionChange`.
+It is always possible to reschedule a version change. In order to cancel a scheduled version
+change rather than reschedule it, a new version change should be scheduled with
+`version_incoming` set to the current value of `FinalityVersion`.
+
+License: Apache 2.0

pallets/aleph/src/lib.rs

@@ -1,20 +1,5 @@
-//! This pallet is the runtime companion of the Aleph finality gadget.
-//!
-//! Currently, it only provides support for changing sessions but in the future
-//! it will allow reporting equivocation in AlephBFT.
-//!
-//! This pallet relies on an extension of the `AlephSessionApi` Runtime API to handle the finality
-//! version. The scheduled version change is persisted as `FinalityScheduledVersionChange`. This
-//! value stores the information about a scheduled finality version change, where `version_incoming`
-//! is the version to be set and `session` is the session on which the new version will be set.
-//! A `pallet_session::Session_Manager` checks whether a scheduled version change has moved into
-//! the past and, if so, records it as the current version represented as `FinalityVersion`,
-//! and clears `FinalityScheduledVersionChange`.
-//! It is always possible to reschedule a version change. In order to cancel a scheduled version
-//! change rather than reschedule it, a new version change should be scheduled with
-//! `version_incoming` set to the current value of `FinalityVersion`.
-
 #![cfg_attr(not(feature = "std"), no_std)]
+#![doc = include_str!("../README.md")]
 
 #[cfg(test)]
 mod mock;
@@ -43,6 +28,7 @@ const STORAGE_VERSION: StorageVersion = StorageVersion::new(2);
 pub(crate) const LOG_TARGET: &str = "pallet-aleph";
 
 #[frame_support::pallet]
+#[pallet_doc("../README.md")]
 pub mod pallet {
     use frame_support::{pallet_prelude::*, sp_runtime::RuntimeAppPublic};
     use frame_system::{

pallets/committee-management/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pallet-committee-management"
-version = "0.1.0"
+version = "0.2.0"
 authors.workspace = true
 edition.workspace = true
 homepage.workspace = true

pallets/committee-management/README.md

@@ -0,0 +1,21 @@
+# pallet-committee-management
+
+## Ban logic
+In case of insufficient validator's uptime, we need to remove such validators from
+the committee, so that the network is as healthy as possible. This is achieved by calculating
+number of _underperformance_ sessions, which means that number of blocks produced by the
+validator is less than some predefined threshold.
+In other words, if a validator:
+* performance in a session is less or equal to a configurable threshold
+`BanConfig::minimal_expected_performance` (from 0 to 100%), and,
+* it happened at least `BanConfig::underperformed_session_count_threshold` times,
+then the validator is considered an underperformer and hence removed (ie _banned out_) from the
+committee.
+
+### Thresholds
+There are two ban thresholds described above, see [`BanConfig`].
+
+#### Next era vs current era
+Current and next era have distinct thresholds values, as we calculate bans during the start of the new era.
+They follow the same logic as next era committee seats: at the time of planning the first
+session of next the era, next values become current ones.

pallets/committee-management/src/lib.rs

@@ -1,24 +1,5 @@
 #![cfg_attr(not(feature = "std"), no_std)]
-//!
-//! # Ban logic
-//! In case of insufficient validator's uptime, we need to remove such validators from
-//! the committee, so that the network is as healthy as possible. This is achieved by calculating
-//! number of _underperformance_ sessions, which means that number of blocks produced by the
-//! validator is less than some predefined threshold.
-//! In other words, if a validator:
-//! * performance in a session is less or equal to a configurable threshold
-//! `BanConfig::minimal_expected_performance` (from 0 to 100%), and,
-//! * it happened at least `BanConfig::underperformed_session_count_threshold` times,
-//! then the validator is considered an underperformer and hence removed (ie _banned out_) from the
-//! committee.
-//!
-//! ## Thresholds
-//! There are two ban thresholds described above, see [`BanConfig`].
-//!
-//! ### Next era vs current era
-//! Current and next era have distinct thresholds values, as we calculate bans during the start of the new era.
-//! They follow the same logic as next era committee seats: at the time of planning the first
-//! session of next the era, next values become current ones.
+#![doc = include_str!("../README.md")]
 
 extern crate core;
 
@@ -67,6 +48,7 @@ const STORAGE_VERSION: StorageVersion = StorageVersion::new(0);
 pub(crate) const LOG_TARGET: &str = "pallet-committee-management";
 
 #[frame_support::pallet]
+#[pallet_doc("../README.md")]
 pub mod pallet {
     use frame_support::{
         dispatch::DispatchResult, ensure, pallet_prelude::*, BoundedVec, Twox64Concat,
@@ -151,7 +133,7 @@ pub mod pallet {
         InvalidBanConfig,
 
         /// Ban reason is too big, ie given vector of bytes is greater than
-        /// [`Config::MaximumBanReasonLength`]
+        /// [`primitives::DEFAULT_BAN_REASON_LENGTH`]
         BanReasonTooBig,
 
         /// Lenient threshold not in [0-100] range

pallets/committee-management/src/manager.rs

@@ -18,8 +18,8 @@ use crate::{
 /// *  We update rewards and clear block count for the session `S`.
 /// 3. `start_session(S + 1)` is called.
 /// *  if session `S+1` starts new era we populate totals and unban all validators whose ban expired.
-/// *  if session `S+1` % [`BanConfig::clean_session_counter_delay`] == 0, we
-///    clean up underperformed session counter
+/// *  if session `S+1` % `clean_session_counter_delay` == 0, we clean up underperformed session counter.
+/// * `clean_session_counter_delay` is read from pallet's storage
 /// 4. `new_session(S + 2)` is called.
 /// *  If session `S+2` starts new era we emit fresh bans events
 /// *  We rotate the validators for session `S + 2` using the information about reserved and non reserved validators.

pallets/elections/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pallet-elections"
-version = "0.5.4"
+version = "0.6.0"
 license = "Apache 2.0"
 authors.workspace = true
 edition.workspace = true

pallets/elections/README.md

@@ -0,0 +1,17 @@
+# pallet-elections
+
+This pallet manages changes in the committee responsible for producing blocks and establishing consensus.
+
+## Terminology
+For definition of session, era, staking see pallet_session and pallet_staking.
+- committee ([`EraValidators`]): Set of nodes that produce and finalize blocks in the session.
+- validator: Node that can become a member of committee (or already is) via rotation.
+- `EraValidators::reserved`: immutable validators, ie they cannot be removed from that list.
+- `EraValidators::non_reserved`: validators that can be banned out from that list.
+
+## Elections process
+There are two options for choosing validators during election process governed by ([`Openness`]) storage value:
+- `Permissionless`: choose all validators that bonded enough amount and are not banned.
+- `Permissioned`: choose `EraValidators::reserved` and all `EraValidators::non_reserved` that are not banned.
+
+License: Apache 2.0

pallets/elections/src/lib.rs

@@ -1,18 +1,5 @@
-//! This pallet manages changes in the committee responsible for producing blocks and establishing consensus.
-//!
-//! # Terminology
-//! For definition of session, era, staking see pallet_session and pallet_staking.
-//! - committee ([`EraValidators`]): Set of nodes that produce and finalize blocks in the session.
-//! - validator: Node that can become a member of committee (or already is) via rotation.
-//! - `EraValidators::reserved`: immutable validators, ie they cannot be removed from that list.
-//! - `EraValidators::non_reserved`: validators that can be banned out from that list.
-//!
-//! # Elections process
-//! There are two options for choosing validators during election process governed by ([`Openness`]) storage value:
-//! - `Permissionless`: choose all validators that bonded enough amount and are not banned.
-//! - `Permissioned`: choose `EraValidators::reserved` and all `EraValidators::non_reserved` that are not banned.
-
 #![cfg_attr(not(feature = "std"), no_std)]
+#![doc = include_str!("../README.md")]
 
 mod impls;
 #[cfg(test)]
@@ -39,6 +26,7 @@ const STORAGE_VERSION: StorageVersion = StorageVersion::new(5);
 pub struct ValidatorTotalRewards<T>(pub BTreeMap<T, TotalReward>);
 
 #[frame_support::pallet]
+#[pallet_doc("../README.md")]
 pub mod pallet {
     use frame_election_provider_support::{
         BoundedSupportsOf, ElectionDataProvider, ElectionProvider, ElectionProviderBase, Support,

scripts/run_checks_on_excluded_packages.sh

@@ -37,7 +37,6 @@ for p in ${packages[@]}; do
     cargo clippy -- --no-deps -D warnings
   fi
 
-  cargo +nightly-2023-01-10 fmt --all --check
   popd
 
 done