diff --git a/sway-lib-std/src/token.sw b/sway-lib-std/src/token.sw
index 2ee0ce314f5..716161357b6 100644
--- a/sway-lib-std/src/token.sw
+++ b/sway-lib-std/src/token.sw
@@ -13,27 +13,29 @@ use ::outputs::{Output, output_amount, output_count, output_type};
 /// to `to` by calling either `force_transfer_to_contract` or
 /// `transfer_to_address`, depending on the type of `Identity`.
 ///
-/// > **_WARNING:_**
-/// >
-/// > If the `to` Identity is a contract, this will transfer coins to the contract even with no way to retrieve them
-/// > (i.e: no withdrawal functionality on the receiving contract), possibly leading to
-/// > the **_PERMANENT LOSS OF COINS_** if not used with care.
+/// # Additional Information
+/// 
+/// If the `to` Identity is a contract, this will transfer coins to the contract even with no way to retrieve them
+/// (i.e: no withdrawal functionality on the receiving contract), possibly leading to
+/// the **_PERMANENT LOSS OF COINS_** if not used with care.
 ///
-/// ### Arguments
+/// # Arguments
 ///
-/// * `amount` - The amount of tokens to mint.
-/// * `to` - The `Identity` to which to send the tokens.
+/// * `amount`: [u64] - The amount of tokens to mint.
+/// * `to`: [Identity] - The recipient identity.
 ///
-/// ### Examples
+/// # Examples
 ///
 /// ```sway
 /// use std::{constants::ZERO_B256, token::mint_to};
 ///
-/// // replace the zero Address/ContractId with your desired Address/ContractId
-/// let to_address = Identity::Address(Address::from(ZERO_B256));
-/// let to_contract_id = Identity::ContractId(ContractId::from(ZERO_B256));
-/// mint_to(500, to_address);
-/// mint_to(500, to_contract_id);
+/// fn foo() {
+///     // replace the zero Address/ContractId with your desired Address/ContractId
+///     let to_address = Identity::Address(Address::from(ZERO_B256));
+///     let to_contract_id = Identity::ContractId(ContractId::from(ZERO_B256));
+///     mint_to(500, to_address);
+///     mint_to(500, to_contract_id);
+/// }
 /// ```
 pub fn mint_to(amount: u64, to: Identity) {
     mint(amount);
@@ -43,25 +45,27 @@ pub fn mint_to(amount: u64, to: Identity) {
 /// Mint `amount` coins of the current contract's `asset_id` and send them
 /// UNCONDITIONALLY to the contract at `to`.
 ///
-/// > **_WARNING:_**
-/// >
-/// > This will transfer coins to a contract even with no way to retrieve them
-/// > (i.e: no withdrawal functionality on the receiving contract), possibly leading to
-/// > the **_PERMANENT LOSS OF COINS_** if not used with care.
+/// # Additional Information
+/// 
+/// This will transfer coins to a contract even with no way to retrieve them
+/// (i.e: no withdrawal functionality on the receiving contract), possibly leading to
+/// the **_PERMANENT LOSS OF COINS_** if not used with care.
 ///
-/// ### Arguments
+/// # Arguments
 ///
-/// * `amount` - The amount of tokens to mint.
-/// * `to` - The `ContractId` to which to send the tokens.
+/// * `amount`: [u64] - The amount of tokens to mint.
+/// * `to`: [ContractId] - The recipient contract.
 ///
-/// ### Examples
+/// # Examples
 ///
 /// ```sway
 /// use std::{constants::ZERO_B256, token::mint_to_contract};
 ///
-/// // replace the zero ContractId with your desired ContractId
-/// let to = ContractId::from(ZERO_B256);
-/// mint_to_contract(500, to);
+/// fn foo() {
+///     // replace the zero ContractId with your desired ContractId
+///     let to = ContractId::from(ZERO_B256);
+///     mint_to_contract(500, to);
+/// }
 /// ```
 pub fn mint_to_contract(amount: u64, to: ContractId) {
     mint(amount);
@@ -71,19 +75,21 @@ pub fn mint_to_contract(amount: u64, to: ContractId) {
 /// Mint `amount` coins of the current contract's `asset_id` and send them to
 /// the Address `to`.
 ///
-/// ### Arguments
+/// # Arguments
 ///
-/// * `amount` - The amount of tokens to mint.
-/// * `to` - The `Address` to which to send the tokens.
+/// * `amount`: [u64] - The amount of tokens to mint.
+/// * `to`: [Address] - The recipient address.
 ///
-/// ### Examples
+/// # Examples
 ///
 /// ```sway
 /// use std::{constants::ZERO_B256, token::mint_to_address};
 ///
-/// // replace the zero Address with your desired Address
-/// let to = Address::from(ZERO_B256);
-/// mint_to_address(500, to);
+/// fn foo() {
+///     // replace the zero Address with your desired Address
+///     let to = Address::from(ZERO_B256);
+///     mint_to_address(500, to);
+/// }
 /// ```
 pub fn mint_to_address(amount: u64, to: Address) {
     mint(amount);
@@ -92,16 +98,18 @@ pub fn mint_to_address(amount: u64, to: Address) {
 
 /// Mint `amount` coins of the current contract's `asset_id`. The newly minted tokens are owned by the current contract.
 ///
-/// ### Arguments
+/// # Arguments
 ///
-/// * `amount` - The amount of tokens to mint.
+/// * `amount`: [u64] - The amount of tokens to mint.
 ///
-/// ### Examples
+/// # Examples
 ///
 /// ```sway
 /// use std::token::mint;
 ///
-/// mint(500);
+/// fn foo() {
+///     mint(500);
+/// }
 /// ```
 pub fn mint(amount: u64) {
     asm(r1: amount) {
@@ -111,20 +119,22 @@ pub fn mint(amount: u64) {
 
 /// Burn `amount` coins of the current contract's `asset_id`. Burns them from the balance of the current contract.
 ///
-/// ### Arguments
+/// # Arguments
 ///
-/// * `amount` - The amount of tokens to burn.
+/// * `amount`: [u64] - The amount of tokens to burn.
 ///
-/// ### Reverts
+/// # Panics
 ///
-/// Reverts if the contract balance is less than `amount`.
+/// * When the contract balance is less than `amount`.
 ///
-/// ### Examples
+/// # Examples
 ///
 /// ```sway
 /// use std::token::burn;
 ///
-/// burn(500);
+/// fn foo() {
+///     burn(500);
+/// }
 /// ```
 pub fn burn(amount: u64) {
     asm(r1: amount) {
@@ -136,34 +146,36 @@ pub fn burn(amount: u64) {
 /// to `to` by calling either `force_transfer_to_contract` or
 /// `transfer_to_address`, depending on the type of `Identity`.
 ///
-/// > **_WARNING:_**
-/// >
-/// > If the `to` Identity is a contract this may transfer coins to the contract even with no way to retrieve them
-/// > (i.e. no withdrawal functionality on receiving contract), possibly leading
-/// > to the **_PERMANENT LOSS OF COINS_** if not used with care.
+/// # Additional Information
+/// 
+/// If the `to` Identity is a contract this may transfer coins to the contract even with no way to retrieve them
+/// (i.e. no withdrawal functionality on receiving contract), possibly leading
+/// to the **_PERMANENT LOSS OF COINS_** if not used with care.
 ///
-/// ### Arguments
+/// # Arguments
 ///
-/// * `amount` - The amount of tokens to transfer.
-/// * `asset_id` - The `AssetId` of the token to transfer.
-/// * `to` - The `Identity` of the recipient.
+/// * `amount`: [u64] - The amount of tokens to transfer.
+/// * `asset_id`: [AssetId] - The token to transfer.
+/// * `to`: [Identity] - The recipient identity.
 ///
-/// ### Reverts
+/// # Panics
 ///
-/// * If `amount` is greater than the contract balance for `asset_id`.
-/// * If `amount` is equal to zero.
-/// * If there are no free variable outputs when transferring to an `Address`.
+/// * When `amount` is greater than the contract balance for `asset_id`.
+/// * When `amount` is equal to zero.
+/// * When there are no free variable outputs when transferring to an `Address`.
 ///
-/// ### Examples
+/// # Examples
 ///
 /// ```sway
 /// use std::{constants::{BASE_ASSET_ID, ZERO_B256}, token::transfer};
 ///
-/// // replace the zero Address/ContractId with your desired Address/ContractId
-/// let to_address = Identity::Address(Address::from(ZERO_B256));
-/// let to_contract_id = Identity::ContractId(ContractId::from(ZERO_B256));
-/// transfer(500, BASE_ASSET_ID, to_address);
-/// transfer(500, BASE_ASSET_ID, to_contract_id);
+/// fn foo() {
+///     // replace the zero Address/ContractId with your desired Address/ContractId
+///     let to_address = Identity::Address(Address::from(ZERO_B256));
+///     let to_contract_id = Identity::ContractId(ContractId::from(ZERO_B256));
+///     transfer(500, BASE_ASSET_ID, to_address);
+///     transfer(500, BASE_ASSET_ID, to_contract_id);
+/// }
 /// ```
 pub fn transfer(amount: u64, asset_id: AssetId, to: Identity) {
     match to {
@@ -175,31 +187,33 @@ pub fn transfer(amount: u64, asset_id: AssetId, to: Identity) {
 /// UNCONDITIONAL transfer of `amount` coins of type `asset_id` to
 /// the contract at `to`.
 ///
-/// > **_WARNING:_**
-/// >
-/// > This will transfer coins to a contract even with no way to retrieve them
-/// > (i.e. no withdrawal functionality on receiving contract), possibly leading
-/// > to the **_PERMANENT LOSS OF COINS_** if not used with care.
+/// # Additional Information
+/// 
+/// This will transfer coins to a contract even with no way to retrieve them
+/// (i.e. no withdrawal functionality on receiving contract), possibly leading
+/// to the **_PERMANENT LOSS OF COINS_** if not used with care.
 ///
-/// ### Arguments
+/// # Arguments
 ///
-/// * `amount` - The amount of tokens to transfer.
-/// * `asset_id` - The `AssetId` of the token to transfer.
-/// * `to` - The `ContractId` of the recipient contract.
+/// * `amount`: [u64] - The amount of tokens to transfer.
+/// * `asset_id`: [AssetId] - The token to transfer.
+/// * `to`: [ContractId] - The recipient contract.
 ///
-/// ### Reverts
+/// # Reverts
 ///
-/// * If `amount` is greater than the contract balance for `asset_id`.
-/// * If `amount` is equal to zero.
+/// * When `amount` is greater than the contract balance for `asset_id`.
+/// * When `amount` is equal to zero.
 ///
-/// ### Examples
+/// # Examples
 ///
 /// ```sway
 /// use std::{constants::{BASE_ASSET_ID, ZERO_B256}, token::force_transfer_to_contract};
 ///
-/// // replace the zero ContractId with your desired ContractId
-/// let to_contract_id = ContractId::from(ZERO_B256);
-/// force_transfer_to_contract(500, BASE_ASSET_ID, to_contract_id);
+/// fn foo() {
+///     // replace the zero ContractId with your desired ContractId
+///     let to_contract_id = ContractId::from(ZERO_B256);
+///     force_transfer_to_contract(500, BASE_ASSET_ID, to_contract_id);
+/// }
 /// ```
 pub fn force_transfer_to_contract(amount: u64, asset_id: AssetId, to: ContractId) {
     asm(r1: amount, r2: asset_id.value, r3: to.value) {
@@ -210,26 +224,28 @@ pub fn force_transfer_to_contract(amount: u64, asset_id: AssetId, to: ContractId
 /// Transfer `amount` coins of type `asset_id` and send them to
 /// the address `to`.
 ///
-/// ### Arguments
+/// # Arguments
 ///
-/// * `amount` - The amount of tokens to transfer.
-/// * `asset_id` - The `AssetId` of the token to transfer.
-/// * `to` - The `Address` of the recipient user.
+/// * `amount`: [u64] - The amount of tokens to transfer.
+/// * `asset_id`: [AssetId] - The token to transfer.
+/// * `to`: [Address] - The recipient address.
 ///
-/// ### Reverts
+/// # Panics
 ///
-/// * If `amount` is greater than the contract balance for `asset_id`.
-/// * If `amount` is equal to zero.
-/// * If there are no free variable outputs.
+/// * When `amount` is greater than the contract balance for `asset_id`.
+/// * When `amount` is equal to zero.
+/// * When there are no free variable outputs.
 ///
-/// ### Examples
+/// # Examples
 ///
 /// ```sway
 /// use std::{constants::{BASE_ASSET_ID, ZERO_B256}, token::transfer_to_address};
 ///
-/// // replace the zero Address with your desired Address
-/// let to_address = Address::from(ZERO_B256);
-/// transfer_to_address(500, BASE_ASSET_ID, to_address);
+/// fn foo() {
+///     // replace the zero Address with your desired Address
+///     let to_address = Address::from(ZERO_B256);
+///     transfer_to_address(500, BASE_ASSET_ID, to_address);
+/// }
 /// ```
 pub fn transfer_to_address(amount: u64, asset_id: AssetId, to: Address) {
     // maintain a manual index as we only have `while` loops in sway atm: