Add docs about no-op

frame/balances/src/lib.rs

@@ -885,6 +885,8 @@ where
 		Self::free_balance(who) + Self::reserved_balance(who)
 	}
 
+	// Check if `value` amount of free balance can be slashed from `who`.
+	// Is a no-op if value to be slashed is zero.
 	fn can_slash(who: &T::AccountId, value: Self::Balance) -> bool {
 		if value.is_zero() { return true }
 		Self::free_balance(who) >= value
@@ -902,6 +904,8 @@ where
 		<FreeBalance<T, I>>::get(who)
 	}
 
+	// Burn funds from the total issuance, returning a positive imbalance for the amount burned.
+	// Is a no-op if amount to be burned is zero.
 	fn burn(mut amount: Self::Balance) -> Self::PositiveImbalance {
 		if amount.is_zero() { return PositiveImbalance::zero() }
 		<TotalIssuance<T, I>>::mutate(|issued| {
@@ -913,6 +917,9 @@ where
 		PositiveImbalance::new(amount)
 	}
 
+	// Create new funds into the total issuance, returning a negative imbalance
+	// for the amount issued.
+	// Is a no-op if amount to be issued it zero.
 	fn issue(mut amount: Self::Balance) -> Self::NegativeImbalance {
 		if amount.is_zero() { return NegativeImbalance::zero() }
 		<TotalIssuance<T, I>>::mutate(|issued|
@@ -924,6 +931,10 @@ where
 		NegativeImbalance::new(amount)
 	}
 
+	// Ensure that an account can withdraw from their free balance given any existing withdrawal
+	// restrictions like locks and vesting balance.
+	// Is a no-op if amount to be withdrawn is zero.
+	//
 	// # <weight>
 	// Despite iterating over a list of locks, they are limited by the number of
 	// lock IDs, which means the number of runtime modules that intend to use and create locks.
@@ -959,6 +970,8 @@ where
 		}
 	}
 
+	// Transfer some free balance from `transactor` to `dest`, respecting existence requirements.
+	// Is a no-op if value to be transferred is zero.
 	fn transfer(
 		transactor: &T::AccountId,
 		dest: &T::AccountId,
@@ -1006,6 +1019,8 @@ where
 		Ok(())
 	}
 
+	// Withdraw some free balance from an account, respecting existence requirements.
+	// Is a no-op if value to be withdrawn is zero.
 	fn withdraw(
 		who: &T::AccountId,
 		value: Self::Balance,
@@ -1035,6 +1050,7 @@ where
 
 	// Slash an account, returning the negative imbalance created and any left over
 	// amount that could not be slashed.
+	// Is a no-op if value to be slashed is zero.
 	fn slash(
 		who: &T::AccountId,
 		value: Self::Balance
@@ -1060,6 +1076,8 @@ where
 		}
 	}
 
+	// Deposit some `value` into the free balance of an existing account.
+	// Is a no-op if the value to be deposited is zero.
 	fn deposit_into_existing(
 		who: &T::AccountId,
 		value: Self::Balance
@@ -1073,6 +1091,8 @@ where
 		Ok(PositiveImbalance::new(value))
 	}
 
+	// Deposit some `value` into the free balance of `who`, possibly creating a new account.
+	// Is a no-op if the value to be deposited is zero.
 	fn deposit_creating(
 		who: &T::AccountId,
 		value: Self::Balance,
@@ -1137,6 +1157,8 @@ impl<T: Trait<I>, I: Instance> ReservableCurrency<T::AccountId> for Module<T, I>
 where
 	T::Balance: MaybeSerializeDeserialize + Debug
 {
+	// Check if `who` can reserve `value` from their free balance.
+	// Is a no-op if value to be reserved is zero.
 	fn can_reserve(who: &T::AccountId, value: Self::Balance) -> bool {
 		if value.is_zero() { return true }
 		Self::free_balance(who)
@@ -1150,6 +1172,8 @@ where
 		<ReservedBalance<T, I>>::get(who)
 	}
 
+	// Move `value` from the free balance from `who` to their reserved balance.
+	// Is a no-op if value to be reserved is zero.
 	fn reserve(who: &T::AccountId, value: Self::Balance) -> result::Result<(), DispatchError> {
 		if value.is_zero() { return Ok(()) }
 		let b = Self::free_balance(who);
@@ -1164,6 +1188,7 @@ where
 	}
 
 	// Unreserve some funds, returning any amount that was unable to be unreserved.
+	// Is a no-op if the value to be unreserved is zero.
 	fn unreserve(who: &T::AccountId, value: Self::Balance) -> Self::Balance {
 		if value.is_zero() { return Zero::zero() }
 		let b = Self::reserved_balance(who);
@@ -1175,6 +1200,7 @@ where
 
 	// Slash from reserved balance, returning the negative imbalance created,
 	// and any amount that was unable to be slashed.
+	// Is a no-op if the value to be slashed is zero.
 	fn slash_reserved(
 		who: &T::AccountId,
 		value: Self::Balance
@@ -1187,6 +1213,8 @@ where
 		(NegativeImbalance::new(slash), value - slash)
 	}
 
+	// Move the reserved balance of one account into the free balance of another.
+	// Is a no-op if the value to be moved is zero.
 	fn repatriate_reserved(
 		slashed: &T::AccountId,
 		beneficiary: &T::AccountId,
@@ -1210,29 +1238,30 @@ where
 {
 	type Moment = T::BlockNumber;
 
+	// Set a lock on the balance of `who`.
+	// Is a no-op if lock amount is zero.
 	fn set_lock(
 		id: LockIdentifier,
 		who: &T::AccountId,
 		amount: T::Balance,
 		until: T::BlockNumber,
 		reasons: WithdrawReasons,
 	) {
-		if !amount.is_zero(){
-			let now = <frame_system::Module<T>>::block_number();
-			let mut new_lock = Some(BalanceLock { id, amount, until, reasons });
-			let mut locks = Self::locks(who).into_iter().filter_map(|l|
-				if l.id == id {
-					new_lock.take()
-				} else if l.until > now {
-					Some(l)
-				} else {
-					None
-				}).collect::<Vec<_>>();
-			if let Some(lock) = new_lock {
-				locks.push(lock)
-			}
-			<Locks<T, I>>::insert(who, locks);
+		if amount.is_zero() { return }
+		let now = <frame_system::Module<T>>::block_number();
+		let mut new_lock = Some(BalanceLock { id, amount, until, reasons });
+		let mut locks = Self::locks(who).into_iter().filter_map(|l|
+			if l.id == id {
+				new_lock.take()
+			} else if l.until > now {
+				Some(l)
+			} else {
+				None
+			}).collect::<Vec<_>>();
+		if let Some(lock) = new_lock {
+			locks.push(lock)
 		}
+		<Locks<T, I>>::insert(who, locks);
 	}
 
 	fn extend_lock(
@@ -1300,6 +1329,7 @@ where
 	///
 	/// If there already exists a vesting schedule for the given account, an `Err` is returned
 	/// and nothing is updated.
+	/// Is a no-op if the amount to be vested is zero.
 	fn add_vesting_schedule(
 		who: &T::AccountId,
 		locked: T::Balance,