fixed suggestions round 1

srml/balances/README.adoc

@@ -35,27 +35,27 @@ The dispatchable function `transfer` ensures that the sender has signed the tran
 
 The following example shows how to use the balances module in your custom module.
 
-1 Import the `balances` module and derive your module configuration trait with the balances trait.
+1. Import the `balances` module and derive your module configuration trait with the balances trait.
 
-```
+```rust
 use balances;
 
 pub trait Trait: balances::Trait { }
 ```
 
-2 In your module, call the balance module:
+2. In your module, call the balance module:
 
-```
+```rust
 // Get existential deposit
 let ed = Balances::existential_deposit();
 
 // Get transfer fee for the network
 let tf = Balances::transfer_fee();
 ```
 
-3 Include a balance transfer in a block (example from the `executor` module tests):
+3. Include a balance transfer in a block (example from the `executor` module tests):
 
-```
+```rust
 let mut t = new_test_ext(COMPACT_CODE, false);
 let block1 = construct_block(
     &mut t,

srml/balances/src/lib.rs

@@ -231,7 +231,8 @@ impl<T: Trait> Module<T> {
 	/// Doesn't do any preparatory work for creating a new account, so should only be used when it
 	/// is known that the account already exists.
 	///
-	/// Returns either `Updated` or `AccountKilled`.
+	/// Returns `Updated` if the account was successfully updated
+	/// or `AccountKilled` if the update has led to killing the account.
 	pub fn set_reserved_balance(who: &T::AccountId, balance: T::Balance) -> UpdateBalanceOutcome {
 		if balance < Self::existential_deposit() {
 			<ReservedBalance<T>>::insert(who, balance);
@@ -249,7 +250,8 @@ impl<T: Trait> Module<T> {
 	/// Doesn't do any preparatory work for creating a new account, so should only be used when it
 	/// is known that the account already exists.
 	///
-	/// Returns either `Updated` or `AccountKilled`.
+	/// Returns `Updated` if the account was successfully updated
+	/// or `AccountKilled` if the update has led to killing the account.
 	pub fn set_free_balance(who: &T::AccountId, balance: T::Balance) -> UpdateBalanceOutcome {
 		// Commented out for now - but consider it instructive.
 		// assert!(!Self::total_balance(who).is_zero());
@@ -268,7 +270,8 @@ impl<T: Trait> Module<T> {
 	///
 	/// Same as `set_free_balance`, but will create a new account.
 	///
-	/// Returns either `Updated` or `AccountKilled`.
+	/// Returns `Updated` if the account was successfully updated
+	/// or `AccountKilled` if the update has led to killing the account.
 	pub fn set_free_balance_creating(who: &T::AccountId, balance: T::Balance) -> UpdateBalanceOutcome {
 		let ed = <Module<T>>::existential_deposit();
 		// If the balance is too low, then the account is reaped.
@@ -296,9 +299,11 @@ impl<T: Trait> Module<T> {
 
 	/// Transfer some liquid free balance from one account to another.
 	///
-	/// Enforces `ExistentialDeposit` law, reaping the sender's account if it's balance is
+	/// Enforces `ExistentialDeposit` law, reaping the sender's account if its balance is
 	/// too low as a result of the transfer.
 	///
+	/// #NOTES
+	///
 	/// Will create a new account for the destination if the account does not exist.
 	pub fn make_transfer(transactor: &T::AccountId, dest: &T::AccountId, value: T::Balance) -> Result {
 		let from_balance = Self::free_balance(transactor);
@@ -371,14 +376,14 @@ impl<T: Trait> Module<T> {
 		}
 	}
 
-	/// Increase `TotalIssuance` by `value`.
+	/// Increase stake by `value`.
 	pub fn increase_total_stake_by(value: T::Balance) {
 		if let Some(v) = <Module<T>>::total_issuance().checked_add(&value) {
 			<TotalIssuance<T>>::put(v);
 		}
 	}
 
-	/// Decrease `TotalIssuance` by `value`.
+	/// Decrease stake by `value`.
 	pub fn decrease_total_stake_by(value: T::Balance) {
 		if let Some(v) = <Module<T>>::total_issuance().checked_sub(&value) {
 			<TotalIssuance<T>>::put(v);

srml/support/src/traits.rs

@@ -139,7 +139,9 @@ pub trait Currency<AccountId> {
 	/// Returns `Updated` if the account was successfully updated
 	/// or `AccountKilled` if the update has led to killing the account.
 	///
-	/// NOTE: This assumes that the total stake remains unchanged after this operation.
+	/// #NOTES
+	///
+	/// This assumes that the total stake remains unchanged after this operation.
 	fn increase_free_balance_creating(who: &AccountId, value: Self::Balance) -> UpdateBalanceOutcome;
 
 	/// Moves `value` from balance to reserved balance.
@@ -154,9 +156,10 @@ pub trait Currency<AccountId> {
 	/// is less than `value`, then `Some(remaining)` will be returned. If all of `value` is
 	/// moved, the function will return `None`.
 	///
-	/// NOTE: This is different to `reserve`.
+	/// #NOTES
 	///
-	/// NOTE: If the remaining reserved balance is less than `ExistentialDeposit`, it will
+	/// - This is different to `reserve`.
+	/// - If the remaining reserved balance is less than `ExistentialDeposit`, it will
 	/// invoke `on_reserved_too_low` and could reap the account.
 	fn unreserve(who: &AccountId, value: Self::Balance) -> Option<Self::Balance>;