Some code grooming (#2276)

* some code grooming: enable warn(missing_docs) for all piblic crates + added missing documentation + removed obsolete clippy/deny workarounds

* removed strange allow + added comment related to other allow

* removed incorrect_clone_impl_on_copy_type which is unknown to CI clippy

.gitlab-ci.yml

@@ -100,8 +100,7 @@ clippy-nightly:
   variables:
     RUSTFLAGS:                     "-D warnings"
   script:
-    # clippy currently is raising `derive-partial-eq-without-eq` warning even if `Eq` is actually derived
-    - SKIP_WASM_BUILD=1 cargo +nightly clippy --all-targets -- -A clippy::redundant_closure -A clippy::derive-partial-eq-without-eq -A clippy::or_fun_call
+    - SKIP_WASM_BUILD=1 cargo +nightly clippy --all-targets
 
 fmt:
   stage:                           test

bin/runtime-common/src/lib.rs

@@ -16,6 +16,7 @@
 
 //! Common types/functions that may be used by runtimes of all bridged chains.
 
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
 use crate::messages_call_ext::MessagesCallSubType;

bin/runtime-common/src/messages_call_ext.rs

@@ -14,6 +14,9 @@
 // You should have received a copy of the GNU General Public License
 // along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
 
+//! Signed extension for the `pallet-bridge-messages` that is able to reject obsolete
+//! (and some other invalid) transactions.
+
 use bp_messages::{ChainWithMessages, InboundLaneData, LaneId, MessageNonce};
 use bp_runtime::AccountIdOf;
 use frame_support::{dispatch::CallableCallFor, traits::IsSubType, RuntimeDebug};
@@ -105,7 +108,9 @@ impl ReceiveMessagesDeliveryProofInfo {
 /// which tries to update a single lane.
 #[derive(PartialEq, RuntimeDebug)]
 pub enum CallInfo {
+	/// Messages delivery call info.
 	ReceiveMessagesProof(ReceiveMessagesProofInfo),
+	/// Messages delivery confirmation call info.
 	ReceiveMessagesDeliveryProof(ReceiveMessagesDeliveryProofInfo),
 }
 
@@ -121,7 +126,7 @@ impl CallInfo {
 
 /// Helper struct that provides methods for working with a call supported by `CallInfo`.
 pub struct CallHelper<T: Config<I>, I: 'static> {
-	pub _phantom_data: sp_std::marker::PhantomData<(T, I)>,
+	_phantom_data: sp_std::marker::PhantomData<(T, I)>,
 }
 
 impl<T: Config<I>, I: 'static> CallHelper<T, I> {

bin/runtime-common/src/messages_xcm_extension.rs

@@ -57,11 +57,14 @@ where
 	}
 }
 
-/// Message dispatch result type for single message
+/// Message dispatch result type for single message.
 #[derive(CloneNoBound, EqNoBound, PartialEqNoBound, Encode, Decode, Debug, TypeInfo)]
 pub enum XcmBlobMessageDispatchResult {
+	/// We've been unable to decode message payload.
 	InvalidPayload,
+	/// Message has been dispatched.
 	Dispatched,
+	/// Message has **NOT** been dispatched because of given error.
 	NotDispatched(#[codec(skip)] Option<DispatchBlobError>),
 }
 

bin/runtime-common/src/parachains_benchmarking.rs

@@ -60,7 +60,7 @@ where
 	}
 }
 
-pub fn do_prepare_parachain_heads_proof<R, PI, L>(
+fn do_prepare_parachain_heads_proof<R, PI, L>(
 	parachains: &[ParaId],
 	parachain_head_size: u32,
 	proof_params: UnverifiedStorageProofParams,

bin/runtime-common/src/refund_relayer_extension.rs

@@ -118,7 +118,7 @@ where
 
 /// Refund calculator.
 pub trait RefundCalculator {
-	// The underlying integer type in which the refund is calculated.
+	/// The underlying integer type in which the refund is calculated.
 	type Balance;
 
 	/// Compute refund for given transaction.

deny.toml

@@ -50,15 +50,6 @@ notice = "warn"
 ignore = [
     # time (origin: Substrate RPC + benchmarking crates)
     "RUSTSEC-2020-0071",
-    # ansi_term (The maintainer has adviced that this crate is deprecated and will not receive any maintenance.
-    # Once other crates will move to some alternative, we'll do that too)
-    "RUSTSEC-2021-0139",
-    # deprecated parity-wasm (origin: Substrate)
-    "RUSTSEC-2022-0061",
-    # atty (origin: Substrate, clap)
-    "RUSTSEC-2021-0145",
-    # wasmtime (origin: Substrate)
-    "RUSTSEC-2022-0076",
 ]
 # Threshold for security vulnerabilities, any vulnerability with a CVSS score
 # lower than the range specified will be ignored. Note that ignored advisories

modules/beefy/src/lib.rs

@@ -29,6 +29,7 @@
 //! Given the header hash, other pallets are able to verify header-based proofs
 //! (e.g. storage proofs, transaction inclusion proofs, etc.).
 
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
 use bp_beefy::{ChainWithBeefy, InitializationData};

modules/grandpa/src/lib.rs

@@ -32,9 +32,8 @@
 //! Shall the fork occur on the bridged chain governance intervention will be required to
 //! re-initialize the bridge and track the right fork.
 
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
-// Runtime-generated enums
-#![allow(clippy::large_enum_variant)]
 
 pub use storage_types::StoredAuthoritySet;
 
@@ -400,7 +399,9 @@ pub mod pallet {
 	pub enum Event<T: Config<I>, I: 'static = ()> {
 		/// Best finalized chain header has been updated to the header with given number and hash.
 		UpdatedBestFinalizedHeader {
+			/// Number of the new best finalized header.
 			number: BridgedBlockNumber<T, I>,
+			/// Hash of the new best finalized header.
 			hash: BridgedBlockHash<T, I>,
 		},
 	}

modules/messages/src/lib.rs

@@ -33,9 +33,8 @@
 //! If this test fails with your weights, then either weights are computed incorrectly,
 //! or some benchmarks assumptions are broken for your runtime.
 
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
-// Generated by `decl_event!`
-#![allow(clippy::unused_unit)]
 
 pub use inbound_lane::{InboundLane, InboundLaneStorage, StoredInboundLaneData};
 pub use lanes_manager::{
@@ -426,13 +425,24 @@ pub mod pallet {
 	#[pallet::generate_deposit(pub(super) fn deposit_event)]
 	pub enum Event<T: Config<I>, I: 'static = ()> {
 		/// Message has been accepted and is waiting to be delivered.
-		MessageAccepted { lane_id: LaneId, nonce: MessageNonce },
+		MessageAccepted {
+			/// Lane, which has accepted the message.
+			lane_id: LaneId,
+			/// Nonce of accepted message.
+			nonce: MessageNonce,
+		},
 		/// Messages have been received from the bridged chain.
 		MessagesReceived(
+			/// Result of received messages dispatch.
 			ReceivedMessages<<T::MessageDispatch as MessageDispatch>::DispatchLevelResult>,
 		),
 		/// Messages in the inclusive range have been delivered to the bridged chain.
-		MessagesDelivered { lane_id: LaneId, messages: DeliveredMessages },
+		MessagesDelivered {
+			/// Lane for which the delivery has been confirmed.
+			lane_id: LaneId,
+			/// Delivered messages.
+			messages: DeliveredMessages,
+		},
 	}
 
 	#[pallet::error]

modules/parachains/src/lib.rs

@@ -21,6 +21,7 @@
 //! accepts storage proof of some parachain `Heads` entries from bridged relay chain.
 //! It requires corresponding relay headers to be already synced.
 
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
 pub use weights::WeightInfo;
@@ -98,27 +99,49 @@ pub mod pallet {
 	#[pallet::generate_deposit(pub(super) fn deposit_event)]
 	pub enum Event<T: Config<I>, I: 'static = ()> {
 		/// The caller has provided head of parachain that the pallet is not configured to track.
-		UntrackedParachainRejected { parachain: ParaId },
+		UntrackedParachainRejected {
+			/// Identifier of the parachain that is not tracked by the pallet.
+			parachain: ParaId,
+		},
 		/// The caller has declared that he has provided given parachain head, but it is missing
 		/// from the storage proof.
-		MissingParachainHead { parachain: ParaId },
+		MissingParachainHead {
+			/// Identifier of the parachain with missing head.
+			parachain: ParaId,
+		},
 		/// The caller has provided parachain head hash that is not matching the hash read from the
 		/// storage proof.
 		IncorrectParachainHeadHash {
+			/// Identifier of the parachain with incorrect head hast.
 			parachain: ParaId,
+			/// Specified parachain head hash.
 			parachain_head_hash: ParaHash,
+			/// Actual parachain head hash.
 			actual_parachain_head_hash: ParaHash,
 		},
 		/// The caller has provided obsolete parachain head, which is already known to the pallet.
-		RejectedObsoleteParachainHead { parachain: ParaId, parachain_head_hash: ParaHash },
+		RejectedObsoleteParachainHead {
+			/// Identifier of the parachain with obsolete head.
+			parachain: ParaId,
+			/// Obsolete parachain head hash.
+			parachain_head_hash: ParaHash,
+		},
 		/// The caller has provided parachain head that exceeds the maximal configured head size.
 		RejectedLargeParachainHead {
+			/// Identifier of the parachain with rejected head.
 			parachain: ParaId,
+			/// Parachain head hash.
 			parachain_head_hash: ParaHash,
+			/// Parachain head size.
 			parachain_head_size: u32,
 		},
 		/// Parachain head has been updated.
-		UpdatedParachainHead { parachain: ParaId, parachain_head_hash: ParaHash },
+		UpdatedParachainHead {
+			/// Identifier of the parachain that has been updated.
+			parachain: ParaId,
+			/// Parachain head hash.
+			parachain_head_hash: ParaHash,
+		},
 	}
 
 	#[pallet::error]
@@ -137,6 +160,7 @@ pub mod pallet {
 	pub trait BoundedBridgeGrandpaConfig<I: 'static>:
 		pallet_bridge_grandpa::Config<I, BridgedChain = Self::BridgedRelayChain>
 	{
+		/// Type of the bridged relay chain.
 		type BridgedRelayChain: Chain<
 			BlockNumber = RelayBlockNumber,
 			Hash = RelayBlockHash,

modules/shift-session-manager/src/lib.rs

@@ -17,6 +17,7 @@
 //! Substrate session manager that selects 2/3 validators from initial set,
 //! starting from session 2.
 
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
 use frame_support::traits::{ValidatorSet, ValidatorSetWithIdentification};

primitives/chain-bridge-hub-cumulus/src/lib.rs

@@ -14,6 +14,9 @@
 // You should have received a copy of the GNU General Public License
 // along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
 
+//! Primitives of all Cumulus-based bridge hubs.
+
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
 pub use bp_polkadot_core::{
@@ -62,6 +65,7 @@ const MAXIMUM_BLOCK_WEIGHT: Weight = Weight::from_parts(constants::WEIGHT_REF_TI
 pub const AVERAGE_ON_INITIALIZE_RATIO: Perbill = Perbill::from_percent(5);
 
 parameter_types! {
+	/// Size limit of the Cumulus-based bridge hub blocks.
 	pub BlockLength: limits::BlockLength = limits::BlockLength::max_with_normal_ratio(
 		5 * 1024 * 1024,
 		NORMAL_DISPATCH_RATIO,
@@ -74,6 +78,7 @@ parameter_types! {
 	pub const ExtrinsicBaseWeight: Weight = Weight::from_parts(constants::WEIGHT_REF_TIME_PER_NANOS, 0)
 		.saturating_mul(125_000);
 
+	/// Weight limit of the Cumulus-based bridge hub blocks.
 	pub BlockWeights: limits::BlockWeights = limits::BlockWeights::builder()
 		.base_block(BlockExecutionWeight::get())
 		.for_class(DispatchClass::all(), |weights| {

primitives/chain-bridge-hub-kusama/src/lib.rs

@@ -17,6 +17,7 @@
 //! Module with configuration which reflects BridgeHubKusama runtime setup (AccountId, Headers,
 //! Hashes...)
 
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
 pub use bp_bridge_hub_cumulus::*;

primitives/chain-bridge-hub-polkadot/src/lib.rs

@@ -17,6 +17,7 @@
 //! Module with configuration which reflects BridgeHubPolkadot runtime setup
 //! (AccountId, Headers, Hashes...)
 
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
 pub use bp_bridge_hub_cumulus::*;

primitives/chain-bridge-hub-rococo/src/lib.rs

@@ -17,6 +17,7 @@
 //! Module with configuration which reflects BridgeHubRococo runtime setup (AccountId, Headers,
 //! Hashes...)
 
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
 pub use bp_bridge_hub_cumulus::*;

primitives/chain-bridge-hub-wococo/src/lib.rs

@@ -17,6 +17,7 @@
 //! Module with configuration which reflects BridgeHubWococo runtime setup
 //! (AccountId, Headers, Hashes...)
 
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
 pub use bp_bridge_hub_cumulus::*;

primitives/chain-kusama/src/lib.rs

@@ -14,9 +14,10 @@
 // You should have received a copy of the GNU General Public License
 // along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
 
+//! Primitives of the Kusama chain.
+
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
-// RuntimeApi generated functions
-#![allow(clippy::too_many_arguments)]
 
 pub use bp_polkadot_core::*;
 use frame_support::StateVersion;

primitives/chain-millau/src/lib.rs

@@ -14,9 +14,10 @@
 // You should have received a copy of the GNU General Public License
 // along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
 
+//! Primitives of the Millau chain.
+
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
-// RuntimeApi generated functions
-#![allow(clippy::too_many_arguments)]
 
 mod millau_hash;
 
@@ -112,11 +113,16 @@ pub use time_units::*;
 pub mod time_units {
 	use super::BlockNumber;
 
+	/// Milliseconds between Millau chain blocks.
 	pub const MILLISECS_PER_BLOCK: u64 = 6000;
+	/// Slot duration in Millau chain consensus algorithms.
 	pub const SLOT_DURATION: u64 = MILLISECS_PER_BLOCK;
 
+	/// A minute, expressed in Millau chain blocks.
 	pub const MINUTES: BlockNumber = 60_000 / (MILLISECS_PER_BLOCK as BlockNumber);
+	/// A hour, expressed in Millau chain blocks.
 	pub const HOURS: BlockNumber = MINUTES * 60;
+	/// A day, expressed in Millau chain blocks.
 	pub const DAYS: BlockNumber = HOURS * 24;
 }
 
@@ -245,8 +251,10 @@ impl sp_runtime::traits::Hash for BlakeTwoAndKeccak256 {
 }
 
 frame_support::parameter_types! {
+	/// Size limit of the Millau blocks.
 	pub BlockLength: limits::BlockLength =
 		limits::BlockLength::max_with_normal_ratio(2 * 1024 * 1024, NORMAL_DISPATCH_RATIO);
+	/// Weight limit of the Millau blocks.
 	pub BlockWeights: limits::BlockWeights =
 		limits::BlockWeights::with_sensible_defaults(MAXIMUM_BLOCK_WEIGHT, NORMAL_DISPATCH_RATIO);
 }

primitives/chain-polkadot/src/lib.rs

@@ -14,9 +14,10 @@
 // You should have received a copy of the GNU General Public License
 // along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
 
+//! Primitives of the Polkadot chain.
+
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
-// RuntimeApi generated functions
-#![allow(clippy::too_many_arguments)]
 
 pub use bp_polkadot_core::*;
 use frame_support::StateVersion;

primitives/chain-rialto-parachain/src/lib.rs

@@ -14,9 +14,10 @@
 // You should have received a copy of the GNU General Public License
 // along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
 
+//! Primitives of the Rialto parachain.
+
+#![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
-// RuntimeApi generated functions
-#![allow(clippy::too_many_arguments)]
 
 use bp_messages::{
 	ChainWithMessages, InboundMessageDetails, LaneId, MessageNonce, MessagePayload,
@@ -152,8 +153,10 @@ impl ChainWithMessages for RialtoParachain {
 pub use bp_bridge_hub_cumulus::SignedExtension;
 
 frame_support::parameter_types! {
+	/// Size limit of the Rialto parachain blocks.
 	pub BlockLength: limits::BlockLength =
 		limits::BlockLength::max_with_normal_ratio(5 * 1024 * 1024, NORMAL_DISPATCH_RATIO);
+	/// Weight limit of the Rialto parachain blocks.
 	pub BlockWeights: limits::BlockWeights =
 		limits::BlockWeights::with_sensible_defaults(MAXIMUM_BLOCK_WEIGHT, NORMAL_DISPATCH_RATIO);
 }