add handlers documentation

primitives/membership/src/traits.rs

@@ -16,8 +16,11 @@
 
 use frame_support::pallet_prelude::*;
 
+/// A trait defining operations for checking if membership-related operations are allowed.
 pub trait CheckMembershipOpAllowed<IdtyId> {
+    /// Checks if adding a membership is allowed.
     fn check_add_membership(idty_id: IdtyId) -> Result<(), DispatchError>;
+    /// Checks if renewing a membership is allowed.
     fn check_renew_membership(idty_id: IdtyId) -> Result<(), DispatchError>;
 }
 
@@ -31,11 +34,14 @@ impl<IdtyId> CheckMembershipOpAllowed<IdtyId> for () {
     }
 }
 
+/// A trait defining behavior for handling new memberships and membership renewals.
 pub trait OnNewMembership<IdtyId> {
+    /// Called when a new membership is created.
     fn on_created(idty_index: &IdtyId);
     fn on_renewed(idty_index: &IdtyId);
 }
 
+/// Called when an existing membership is renewed.
 pub trait OnRemoveMembership<IdtyId> {
     fn on_removed(idty_index: &IdtyId) -> Weight;
 }

runtime/common/src/handlers.rs

@@ -20,7 +20,8 @@ use frame_support::pallet_prelude::Weight;
 use frame_support::traits::UnfilteredDispatchable;
 use pallet_smith_members::SmithRemovalReason;
 
-// new session handler
+/// OnNewSession handler for the runtime calling all the implementation
+/// of OnNewSession
 pub struct OnNewSessionHandler<Runtime>(core::marker::PhantomData<Runtime>);
 impl<Runtime> pallet_authority_members::traits::OnNewSession for OnNewSessionHandler<Runtime>
 where
@@ -32,13 +33,12 @@ where
     }
 }
 
-/// New membership event runtime handler
+/// Runtime handler for OnNewMembership, calling all implementations of
+/// OnNewMembership and implementing logic at the runtime level.
 pub struct OnNewMembershipHandler<Runtime>(core::marker::PhantomData<Runtime>);
 impl<
         Runtime: frame_system::Config<AccountId = AccountId>
             + pallet_identity::Config<IdtyData = IdtyData, IdtyIndex = IdtyIndex>
-            + pallet_membership::Config
-            + pallet_smith_members::Config<IdtyIndex = IdtyIndex>
             + pallet_duniter_wot::Config
             + pallet_universal_dividend::Config,
     > sp_membership::traits::OnNewMembership<IdtyIndex> for OnNewMembershipHandler<Runtime>
@@ -46,7 +46,8 @@ impl<
     fn on_created(idty_index: &IdtyIndex) {
         // duniter-wot related actions
         pallet_duniter_wot::Pallet::<Runtime>::on_created(idty_index);
-        // when main membership is acquired, it starts getting right to UD
+
+        // When main membership is acquired, it starts getting right to UD.
         pallet_identity::Identities::<Runtime>::mutate_exists(idty_index, |idty_val_opt| {
             if let Some(ref mut idty_val) = idty_val_opt {
                 idty_val.data = IdtyData {
@@ -60,12 +61,14 @@ impl<
     fn on_renewed(_idty_index: &IdtyIndex) {}
 }
 
-/// Remove membership event runtime handler
+/// Runtime handler for OnRemoveMembership, calling all implementations of
+/// OnRemoveMembership and implementing logic at the runtime level.
+/// As the weight accounting is not trivial in this handler, the weight is
+/// done at the handler level.
 pub struct OnRemoveMembershipHandler<Runtime>(core::marker::PhantomData<Runtime>);
 impl<
         Runtime: frame_system::Config<AccountId = AccountId>
             + pallet_identity::Config<IdtyData = IdtyData, IdtyIndex = IdtyIndex>
-            + pallet_membership::Config
             + pallet_smith_members::Config<IdtyIndex = IdtyIndex>
             + pallet_duniter_wot::Config
             + pallet_universal_dividend::Config,
@@ -74,11 +77,12 @@ impl<
     fn on_removed(idty_index: &IdtyIndex) -> Weight {
         // duniter-wot related actions
         let mut weight = pallet_duniter_wot::Pallet::<Runtime>::on_removed(idty_index);
+
         let mut add_db_reads_writes = |reads, writes| {
             weight += crate::constants::DbWeight::get().reads_writes(reads, writes);
         };
 
-        // when membership is removed, call on_removed_member handler which auto claims UD
+        // When membership is removed, call on_removed_member handler which auto claims UD.
         if let Some(idty_value) = pallet_identity::Identities::<Runtime>::get(idty_index) {
             add_db_reads_writes(1, 0);
             if let Some(first_ud_index) = idty_value.data.first_eligible_ud.into() {
@@ -89,12 +93,15 @@ impl<
                 );
             }
         }
-        weight += pallet_smith_members::Pallet::<Runtime>::on_removed_wot_member(*idty_index);
-        weight
+
+        // When membership is removed, also remove from smith member.
+        weight.saturating_add(
+            pallet_smith_members::Pallet::<Runtime>::on_removed_wot_member(*idty_index),
+        )
     }
 }
 
-// spend treasury handler
+/// Runtime handler for TreasurySpendFunds.
 pub struct TreasurySpendFunds<Runtime>(core::marker::PhantomData<Runtime>);
 impl<Runtime> pallet_treasury::SpendFunds<Runtime> for TreasurySpendFunds<Runtime>
 where
@@ -110,6 +117,7 @@ where
     }
 }
 
+/// Runtime handler for OnSmithDelete.
 pub struct OnSmithDeletedHandler<Runtime>(core::marker::PhantomData<Runtime>);
 impl<Runtime> pallet_smith_members::traits::OnSmithDelete<Runtime::MemberId>
     for OnSmithDeletedHandler<Runtime>