Documentation

Author: ndkazu

substrate/frame/conviction-voting/src/traits.rs

@@ -23,6 +23,11 @@ use frame_support::dispatch::DispatchResult;
 use scale_info::TypeInfo;
 use sp_runtime::RuntimeDebug;
 
+
+/// Represents the differents states of a referendum.
+/// None: The referendum is not started.
+/// Ongoing: The referendum is ongoing.
+/// Completed: The referendum is finished.
 #[derive(
 	Encode,
 	Decode,
@@ -45,12 +50,10 @@ pub trait VotingHooks<AccountId, Index, Balance> {
 	fn on_vote(who: &AccountId, ref_index: Index, vote: AccountVote<Balance>) -> DispatchResult;
 
 	// Called when removed vote is executed.
-	// is_finished indicates the state of the referendum = None if referendum is cancelled, Ongoing
-	// if referendum is ongoing and Completed when finished.
 	fn on_remove_vote(who: &AccountId, ref_index: Index, status: Status);
 
-	// Called when removed vote is executed and voter lost the direction to possibly lock some
-	// balance. Can return an amount that should be locked for the conviction time.
+	// Called when a vote is unsuccessful.
+	// Returns the amount of locked balance, which is `None` in the default implementation.
 	fn lock_balance_on_unsuccessful_vote(who: &AccountId, ref_index: Index) -> Option<Balance>;
 
 	/// Will be called by benchmarking before calling `on_vote` in a benchmark.

substrate/frame/conviction-voting/src/vote.rs

@@ -92,6 +92,10 @@ pub enum AccountVote<Balance> {
 	SplitAbstain { aye: Balance, nay: Balance, abstain: Balance },
 }
 
+
+/// present the conditions under which an account's Funds are locked after a voting action.
+/// - `Status(bool)`: Implement a locking period if the referendum passed and `bool` is `true`.
+/// - `Always`: lock the funds regardless of the outcome of the referendum.
 #[derive(
 	Copy,
 	Clone,
@@ -106,7 +110,7 @@ pub enum LockedIf {
 
 impl<Balance: Saturating> AccountVote<Balance> {
 	/// Returns `Some` of the lock periods that the account is locked for, assuming that the
-	/// referendum passed iff `approved` is `true`.
+	/// referendum passed if `approved` is `true`.
 	pub fn locked_if(self, approved: LockedIf) -> Option<(u32, Balance)> {
 		// winning side: can only be removed after the lock period ends.
 		match (self, approved) {