Merge pull request #40 from FuelLabs/bitzoic-update-src-20-example

Add inline documentation for SRC-20 standard examples

examples/src_20/multi_asset/src/multi_asset.sw

@@ -4,34 +4,168 @@ use src_20::SRC20;
 use std::{hash::Hash, storage::storage_string::*, string::String};
 
 storage {
+    /// The total number of distinguishable tokens minted by this contract.
     total_assets: u64 = 0,
+    /// The total supply of tokens for a specific asset minted by this contract.
     total_supply: StorageMap<AssetId, u64> = StorageMap {},
+    /// The name of a specific asset minted by this contract.
     name: StorageMap<AssetId, StorageString> = StorageMap {},
+    /// The symbol of a specific asset minted by this contract.
     symbol: StorageMap<AssetId, StorageString> = StorageMap {},
+    /// The decimals of a specific asset minted by this contract.
     decimals: StorageMap<AssetId, u8> = StorageMap {},
 }
 
 impl SRC20 for Contract {
+    /// Returns the total number of individual assets minted  by this contract.
+    ///
+    /// # Additional Information
+    ///
+    /// For this single asset contract, this is always one.
+    ///
+    /// # Returns
+    ///
+    /// * [u64] - The number of assets that this contract has minted.
+    ///
+    /// # Number of Storage Accesses
+    ///
+    /// * Reads: `1`
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use src_20::SRC20;
+    ///
+    /// fn foo(contract_id: ContractId) {
+    ///     let src_20_abi = abi(SRC20, contract_id);
+    ///     let assets = src_20_abi.total_assets();
+    ///     assert(assets == 1);
+    /// }
+    /// ```
     #[storage(read)]
     fn total_assets() -> u64 {
         storage.total_assets.read()
     }
 
+    /// Returns the total supply of tokens for an asset.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset`: [AssetId] - The asset of which to query the total supply.
+    ///
+    /// # Returns
+    ///
+    /// * [Option<u64>] - The total supply of an `asset`.
+    ///
+    /// # Number of Storage Accesses
+    ///
+    /// * Reads: `1`
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use src_20::SRC20;
+    /// use std::constants::DEFAULT_SUB_ID;
+    ///
+    /// fn foo(contract_id: ContractId) {
+    ///     let src_20_abi = abi(SRC20, contract_id);
+    ///     let supply = src_20_abi.total_supply(DEFAULT_SUB_ID);
+    ///     assert(supply.unwrap() != 0);
+    /// }
+    /// ```
     #[storage(read)]
     fn total_supply(asset: AssetId) -> Option<u64> {
         storage.total_supply.get(asset).try_read()
     }
 
+    /// Returns the name of an asset.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset`: [AssetId] - The asset of which to query the name.
+    ///
+    /// # Returns
+    ///
+    /// * [Option<String>] - The name of `asset`.
+    ///
+    /// # Number of Storage Accesses
+    ///
+    /// * Reads: `1`
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use src_20::SRC20;
+    /// use std::constants::DEFAULT_SUB_ID;
+    ///
+    /// fn foo(contract_id: ContractId) {
+    ///     let src_20_abi = abi(SRC20, contract_id);
+    ///     let name = src_20_abi.name(DEFAULT_SUB_ID);
+    ///     assert(name.is_some());
+    /// }
+    /// ```
     #[storage(read)]
     fn name(asset: AssetId) -> Option<String> {
         storage.name.get(asset).read_slice()
     }
 
+    /// Returns the symbol of am asset.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset`: [AssetId] - The asset of which to query the symbol.
+    ///
+    /// # Returns
+    ///
+    /// * [Option<String>] - The symbol of `asset`.
+    ///
+    /// # Number of Storage Accesses
+    ///
+    /// * Reads: `1`
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use src_20::SRC20;
+    /// use std::constants::DEFAULT_SUB_ID;
+    ///
+    /// fn foo(contract_id: ContractId) {
+    ///     let src_20_abi = abi(SRC20, contract_id);
+    ///     let symbol = src_20_abi.symbol(DEFAULT_SUB_ID);
+    ///     assert(symbol.is_some());
+    /// }
+    /// ```
     #[storage(read)]
     fn symbol(asset: AssetId) -> Option<String> {
         storage.symbol.get(asset).read_slice()
     }
 
+    /// Returns the number of decimals an asset uses.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset`: [AssetId] - The asset of which to query the decimals.
+    ///
+    /// # Returns
+    ///
+    /// * [Option<u8>] - The decimal precision used by `asset`.
+    ///
+    /// # Number of Storage Accesses
+    ///
+    /// * Reads: `1`
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use src_20::SRC20;
+    /// use std::constants::DEFAULT_SUB_ID;
+    ///
+    /// fn foo(contract_id: ContractId) {
+    ///     let src_20_abi = abi(SRC20, contract_id);
+    ///     let decimals = src_20_abi.decimals(DEFAULT_SUB_ID);
+    ///     assert(decimals.unwrap() == 9u8);
+    /// }
+    /// ```
     #[storage(read)]
     fn decimals(asset: AssetId) -> Option<u8> {
         storage.decimals.get(asset).try_read()

examples/src_20/single_asset/src/single_asset.sw

@@ -4,16 +4,65 @@ use src_20::SRC20;
 use std::{call_frames::contract_id, string::String};
 
 configurable {
+    /// The total supply of tokens for the asset minted by this contract.
     TOTAL_SUPPLY: u64 = 100_000_000,
+    /// The decimals of the asset minted by this contract.
     DECIMALS: u8 = 9u8,
+    /// The name of the asset minted by this contract.
+    NAME: str[7] = __to_str_array("MyToken"),
+    /// The symbol of the asset minted by this contract.
+    SYMBOL: str[5] = __to_str_array("MYTKN"),
 }
 
 impl SRC20 for Contract {
+    /// Returns the total number of individual assets minted by a contract.
+    ///
+    /// # Additional Information
+    ///
+    /// For this single asset contract, this is always one.
+    ///
+    /// # Returns
+    ///
+    /// * [u64] - The number of assets that this contract has minted.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use src_20::SRC20;
+    ///
+    /// fn foo(contract_id: ContractId) {
+    ///     let src_20_abi = abi(SRC20, contract_id);
+    ///     let assets = src_20_abi.total_assets();
+    ///     assert(assets == 1);
+    /// }
+    /// ```
     #[storage(read)]
     fn total_assets() -> u64 {
         1
     }
 
+    /// Returns the total supply of tokens for the asset.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset`: [AssetId] - The asset of which to query the total supply, this should be the default `SubId`.
+    ///
+    /// # Returns
+    ///
+    /// * [Option<u64>] - The total supply of an `asset`.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use src_20::SRC20;
+    /// use std::constants::DEFAULT_SUB_ID;
+    ///
+    /// fn foo(contract_id: ContractId) {
+    ///     let src_20_abi = abi(SRC20, contract_id);
+    ///     let supply = src_20_abi.total_supply(DEFAULT_SUB_ID);
+    ///     assert(supply.unwrap() != 0);
+    /// }
+    /// ```
     #[storage(read)]
     fn total_supply(asset: AssetId) -> Option<u64> {
         if asset == AssetId::default(contract_id()) {
@@ -23,24 +72,90 @@ impl SRC20 for Contract {
         }
     }
 
+    /// Returns the name of the asset.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset`: [AssetId] - The asset of which to query the name, this should be the default `SubId`.
+    ///
+    /// # Returns
+    ///
+    /// * [Option<String>] - The name of `asset`.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use src_20::SRC20;
+    /// use std::constants::DEFAULT_SUB_ID;
+    ///
+    /// fn foo(contract_id: ContractId) {
+    ///     let src_20_abi = abi(SRC20, contract_id);
+    ///     let name = src_20_abi.name(DEFAULT_SUB_ID);
+    ///     assert(name.is_some());
+    /// }
+    /// ```
     #[storage(read)]
     fn name(asset: AssetId) -> Option<String> {
         if asset == AssetId::default(contract_id()) {
-            Some(String::from_ascii_str("MyToken"))
+            Some(String::from_ascii_str(from_str_array(NAME)))
         } else {
             None
         }
     }
 
+    /// Returns the symbol of the asset.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset`: [AssetId] - The asset of which to query the symbol, this should be the default `SubId`.
+    ///
+    /// # Returns
+    ///
+    /// * [Option<String>] - The symbol of `asset`.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use src_20::SRC20;
+    /// use std::constants::DEFAULT_SUB_ID;
+    ///
+    /// fn foo(contract_id: ContractId) {
+    ///     let src_20_abi = abi(SRC20, contract_id);
+    ///     let symbol = src_20_abi.symbol(DEFAULT_SUB_ID);
+    ///     assert(symbol.is_some());
+    /// }
+    /// ```
     #[storage(read)]
     fn symbol(asset: AssetId) -> Option<String> {
         if asset == AssetId::default(contract_id()) {
-            Some(String::from_ascii_str("MYTKN"))
+            Some(String::from_ascii_str(from_str_array(SYMBOL)))
         } else {
             None
         }
     }
 
+    /// Returns the number of decimals the asset uses.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset`: [AssetId] - The asset of which to query the decimals, this should be the default `SubId`.
+    ///
+    /// # Returns
+    ///
+    /// * [Option<u8>] - The decimal precision used by `asset`.
+    ///
+    /// # Examples
+    ///
+    /// ```sway
+    /// use src_20::SRC20;
+    /// use std::constants::DEFAULT_SUB_ID;
+    ///
+    /// fn foo(contract_id: ContractId) {
+    ///     let src_20_abi = abi(SRC20, contract_id);
+    ///     let decimals = src_20_abi.decimals(DEFAULT_SUB_ID);
+    ///     assert(decimals.unwrap() == 9u8);
+    /// }
+    /// ```
     #[storage(read)]
     fn decimals(asset: AssetId) -> Option<u8> {
         if asset == AssetId::default(contract_id()) {