refactor: add comments

pop-api/examples/fungibles/lib.rs

@@ -7,14 +7,11 @@ use pop_api::{
 		self as api,
 		events::Created,
 		traits::{Psp22, Psp22Burnable, Psp22Metadata, Psp22Mintable},
-		PSP22Error, PSP22Result,
+		PSP22Error,
 	},
 	StatusCode,
 };
 
-#[cfg(test)]
-mod tests;
-
 #[ink::contract]
 mod fungibles {
 	use super::*;
@@ -30,7 +27,7 @@ mod fungibles {
 		/// # Parameters
 		/// * - `token` - The token.
 		#[ink(constructor, payable)]
-		pub fn new_existing(id: TokenId) -> PSP22Result<Self> {
+		pub fn new_existing(id: TokenId) -> Result<Self, PSP22Error> {
 			// Make sure token exists.
 			if !api::token_exists(id).unwrap_or_default() {
 				return Err(PSP22Error::Custom(String::from("Unknown")));
@@ -47,7 +44,11 @@ mod fungibles {
 		/// * - `admin` - The account that will administer the token.
 		/// * - `min_balance` - The minimum balance required for accounts holding this token.
 		#[ink(constructor, payable)]
-		pub fn new(id: TokenId, admin: AccountId, min_balance: Balance) -> PSP22Result<Self> {
+		pub fn new(
+			id: TokenId,
+			admin: AccountId,
+			min_balance: Balance,
+		) -> Result<Self, PSP22Error> {
 			api::create(id, admin, min_balance).map_err(PSP22Error::from)?;
 			let contract = Self { id };
 			contract
@@ -58,81 +59,101 @@ mod fungibles {
 	}
 
 	impl Psp22 for Fungibles {
+		/// Returns the total token supply.
 		#[ink(message)]
 		fn total_supply(&self) -> Balance {
 			api::total_supply(self.id).unwrap_or_default()
 		}
-
+		/// Returns the account balance for the specified `owner`
 		#[ink(message)]
 		fn balance_of(&self, owner: AccountId) -> Balance {
 			api::balance_of(self.id, owner).unwrap_or_default()
 		}
-
+		/// Returns the amount which `spender` is still allowed to withdraw from `owner`
 		#[ink(message)]
 		fn allowance(&self, owner: AccountId, spender: AccountId) -> Balance {
 			api::allowance(self.id, owner, spender).unwrap_or_default()
 		}
-
+		/// Transfers `value` amount of tokens from the caller's account to account `to`
+		/// with additional `data` in unspecified format.
 		#[ink(message)]
-		fn transfer(&mut self, to: AccountId, value: Balance, _data: Vec<u8>) -> PSP22Result<()> {
+		fn transfer(
+			&mut self,
+			to: AccountId,
+			value: Balance,
+			_data: Vec<u8>,
+		) -> Result<(), PSP22Error> {
 			api::transfer(self.id, to, value).map_err(PSP22Error::from)
 		}
-
+		/// Transfers `value` tokens on the behalf of `from` to the account `to`
+		/// with additional `data` in unspecified format.
 		#[ink(message)]
 		fn transfer_from(
 			&mut self,
 			from: AccountId,
 			to: AccountId,
 			value: Balance,
 			_data: Vec<u8>,
-		) -> PSP22Result<()> {
+		) -> Result<(), PSP22Error> {
 			api::transfer_from(self.id, from, to, value).map_err(PSP22Error::from)
 		}
-
+		/// Allows `spender` to withdraw from the caller's account multiple times, up to
+		/// the total amount of `value`.
 		#[ink(message)]
-		fn approve(&mut self, spender: AccountId, value: Balance) -> PSP22Result<()> {
+		fn approve(&mut self, spender: AccountId, value: Balance) -> Result<(), PSP22Error> {
 			api::approve(self.id, spender, value).map_err(PSP22Error::from)
 		}
-
+		/// Increases by `value` the allowance granted to `spender` by the caller.
 		#[ink(message)]
-		fn increase_allowance(&mut self, spender: AccountId, value: Balance) -> PSP22Result<()> {
+		fn increase_allowance(
+			&mut self,
+			spender: AccountId,
+			value: Balance,
+		) -> Result<(), PSP22Error> {
 			api::increase_allowance(self.id, spender, value).map_err(PSP22Error::from)
 		}
-
+		/// Decreases by `value` the allowance granted to `spender` by the caller.
 		#[ink(message)]
-		fn decrease_allowance(&mut self, spender: AccountId, value: Balance) -> PSP22Result<()> {
+		fn decrease_allowance(
+			&mut self,
+			spender: AccountId,
+			value: Balance,
+		) -> Result<(), PSP22Error> {
 			api::decrease_allowance(self.id, spender, value).map_err(PSP22Error::from)
 		}
 	}
 
-	impl Psp22Mintable for Fungibles {
-		#[ink(message)]
-		fn mint(&mut self, account: AccountId, amount: Balance) -> PSP22Result<()> {
-			api::mint(self.id, account, amount).map_err(PSP22Error::from)
-		}
-	}
-
-	impl Psp22Burnable for Fungibles {
-		#[ink(message)]
-		fn burn(&mut self, account: AccountId, amount: Balance) -> PSP22Result<()> {
-			api::burn(self.id, account, amount).map_err(PSP22Error::from)
-		}
-	}
-
 	impl Psp22Metadata for Fungibles {
+		/// Returns the token name.
 		#[ink(message)]
 		fn token_name(&self) -> Option<String> {
 			api::token_name(self.id).ok().and_then(|v| String::from_utf8(v).ok())
 		}
-
+		/// Returns the token symbol.
 		#[ink(message)]
 		fn token_symbol(&self) -> Option<String> {
 			api::token_symbol(self.id).ok().and_then(|v| String::from_utf8(v).ok())
 		}
-
+		/// Returns the token decimals.
 		#[ink(message)]
 		fn token_decimals(&self) -> u8 {
 			api::token_decimals(self.id).unwrap_or_default()
 		}
 	}
+
+	impl Psp22Mintable for Fungibles {
+		/// Mints `value` tokens to the senders account.
+		#[ink(message)]
+		fn mint(&mut self, account: AccountId, amount: Balance) -> Result<(), PSP22Error> {
+			api::mint(self.id, account, amount).map_err(PSP22Error::from)
+		}
+	}
+
+	impl Psp22Burnable for Fungibles {
+		/// Burns `value` tokens from the senders account.
+		#[ink(message)]
+		fn burn(&mut self, account: AccountId, amount: Balance) -> Result<(), PSP22Error> {
+			api::burn(self.id, account, amount).map_err(PSP22Error::from)
+		}
+	}
 }