more doc

pallets/certification/src/lib.rs

@@ -269,6 +269,7 @@ pub mod pallet {
 
     #[pallet::call]
     impl<T: Config<I>, I: 'static> Pallet<T, I> {
+        /// add a certification without checks (only root)
         #[pallet::weight(1_000_000_000)]
         pub fn force_add_cert(
             origin: OriginFor<T>,
@@ -355,6 +356,7 @@ pub mod pallet {
             Self::do_add_cert(block_number, issuer, receiver)
         }
 
+        /// remove a certification (only root)
         #[pallet::weight(1_000_000_000)]
         pub fn del_cert(
             origin: OriginFor<T>,
@@ -366,6 +368,7 @@ pub mod pallet {
             Ok(().into())
         }
 
+        /// remove all certifications received by an identity (only root)
         #[pallet::weight(1_000_000_000)]
         pub fn remove_all_certs_received_by(
             origin: OriginFor<T>,
@@ -382,6 +385,7 @@ pub mod pallet {
     // INTERNAL FUNCTIONS //
 
     impl<T: Config<I>, I: 'static> Pallet<T, I> {
+        /// perform cert add
         fn do_add_cert(
             block_number: T::BlockNumber,
             issuer: T::IdtyIndex,
@@ -438,6 +442,7 @@ pub mod pallet {
 
             Ok(().into())
         }
+        /// remove the certifications due to expire on the given block
         fn prune_certifications(block_number: T::BlockNumber) -> Weight {
             let mut total_weight = Weight::zero();
 
@@ -449,6 +454,7 @@ pub mod pallet {
 
             total_weight
         }
+        /// perform the certification removal
         fn remove_cert_inner(
             issuer: T::IdtyIndex,
             receiver: T::IdtyIndex,
@@ -505,6 +511,7 @@ pub mod pallet {
     }
 }
 
+// implement setting next_issuable_on for certification period
 impl<T: Config<I>, I: 'static> SetNextIssuableOn<T::BlockNumber, T::IdtyIndex> for Pallet<T, I> {
     fn set_next_issuable_on(idty_index: T::IdtyIndex, next_issuable_on: T::BlockNumber) -> Weight {
         <StorageIdtyCertMeta<T, I>>::mutate_exists(idty_index, |cert_meta_opt| {

pallets/certification/src/types.rs

@@ -20,10 +20,14 @@ use codec::{Decode, Encode};
 use frame_support::pallet_prelude::*;
 use scale_info::TypeInfo;
 
+/// certification metadata attached to an identity
 #[derive(Encode, Decode, Clone, Copy, PartialEq, Eq, RuntimeDebug, TypeInfo)]
 pub struct IdtyCertMeta<BlockNumber: Default> {
+    /// count issued certifications
     pub issued_count: u32,
+    /// block before which identity not allowed to issue a new certification
     pub next_issuable_on: BlockNumber,
+    /// number of certifications received
     pub received_count: u32,
 }
 

pallets/universal-dividend/src/lib.rs

@@ -254,7 +254,9 @@ pub mod pallet {
 
     // INTERNAL FUNCTIONS //
     impl<T: Config> Pallet<T> {
+        /// create universal dividend
         fn create_ud(members_count: BalanceOf<T>) {
+            // get current value of UD and monetary mass
             let ud_amount = <CurrentUd<T>>::get();
             let monetary_mass = <MonetaryMass<T>>::get();
 
@@ -263,9 +265,14 @@ pub mod pallet {
                 core::mem::replace(next_ud_index, next_ud_index.saturating_add(1))
             });
 
+            // compute the new monetary mass
             let new_monetary_mass =
                 monetary_mass.saturating_add(ud_amount.saturating_mul(members_count));
+
+            // update the storage value of the monetary mass
             MonetaryMass::<T>::put(new_monetary_mass);
+
+            // emit an event to inform blockchain users that the holy UNIVERSAL DIVIDEND was created
             Self::deposit_event(Event::NewUdCreated {
                 amount: ud_amount,
                 index: ud_index,
@@ -273,6 +280,8 @@ pub mod pallet {
                 monetary_mass: new_monetary_mass,
             });
         }
+
+        /// claim all due universal dividend at a time
         fn do_claim_uds(who: &T::AccountId) -> DispatchResultWithPostInfo {
             T::MembersStorage::try_mutate_exists(who, |maybe_first_eligible_ud| {
                 if let Some(FirstEligibleUd(Some(ref mut first_ud_index))) = maybe_first_eligible_ud
@@ -304,6 +313,8 @@ pub mod pallet {
                 }
             })
         }
+
+        /// like balance.transfer, but give an amount in UD
         fn do_transfer_ud(
             origin: OriginFor<T>,
             dest: <T::Lookup as StaticLookup>::Source,
@@ -321,11 +332,14 @@ pub mod pallet {
             )?;
             Ok(().into())
         }
+
+        /// reevaluate the value of the universal dividend
         fn reeval_ud(members_count: BalanceOf<T>) {
+            // get current value and monetary mass
             let ud_amount = <CurrentUd<T>>::get();
-
             let monetary_mass = <MonetaryMass<T>>::get();
 
+            // compute new value
             let new_ud_amount = Self::reeval_ud_formula(
                 ud_amount,
                 T::SquareMoneyGrowthRate::get(),
@@ -336,6 +350,7 @@ pub mod pallet {
                 ),
             );
 
+            // update the storage value and the history of past reevals
             CurrentUd::<T>::put(new_ud_amount);
             PastReevals::<T>::mutate(|past_reevals| {
                 if past_reevals.len() == T::MaxPastReeval::get() as usize {
@@ -352,6 +367,8 @@ pub mod pallet {
                 members_count,
             });
         }
+
+        /// formula for Universal Dividend reevaluation
         fn reeval_ud_formula(
             ud_t: BalanceOf<T>,
             c_square: Perbill,
@@ -406,6 +423,8 @@ pub mod pallet {
         pub fn init_first_eligible_ud() -> FirstEligibleUd {
             CurrentUdIndex::<T>::get().into()
         }
+        /// function to call when removing a member
+        /// auto-claims UDs
         pub fn on_removed_member(first_ud_index: UdIndex, who: &T::AccountId) -> Weight {
             let current_ud_index = CurrentUdIndex::<T>::get();
             if first_ud_index < current_ud_index {