Skip to content

Commit

Permalink
Update inline docs of address, contract id, and identity to meet SRC-…
Browse files Browse the repository at this point in the history 
…2 standards (#4837)

## Description

Updated the `contract_id.sw`, `address.sw`, and `identity.sw` files to
meet the SRC-2 inline documentation standard.

This PR completes the following tasks of
#4812
 - address.sw
 - contract_id.sw
 - identity.sw
 
## Checklist

- [x] I have linked to any relevant issues.
- [x] I have commented my code, particularly in hard-to-understand
areas.
- [x] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [x] I have added tests that prove my fix is effective or that my
feature works.
- [x] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [x] I have done my best to ensure that my PR adheres to [the Fuel Labs
Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [x] I have requested a review from the relevant team or maintainers.

---------

Co-authored-by: bitzoic <bitzoic.eth@gmail.com>
Co-authored-by: JoshuaBatty <joshpbatty@gmail.com>
  • Loading branch information
@bitzoic @JoshuaBatty
3 people authored Jul 27, 2023
1 parent 2dd2072 commit 2a4f6fb
Show file tree
Hide file tree
Showing 4 changed files with 233 additions and 77 deletions.
75 changes: 58 additions & 17 deletions sway-lib-std/src/address.sw
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ use ::outputs::{Output, output_amount, output_count, output_type};

/// The `Address` type, a struct wrapper around the inner `b256` value.
pub struct Address {
/// The underlying raw `b256` data of the address.
value: b256,
}

Expand All @@ -21,10 +22,46 @@ impl core::ops::Eq for Address {

/// Functions for casting between the `b256` and `Address` types.
impl From<b256> for Address {
/// Casts raw `b256` data to an `Address`.
///
/// # Arguments
///
/// * `bits`: [b256] - The raw `b256` data to be casted.
///
/// # Returns
///
/// * [Address] - The newly created `Address` from the raw `b256`.
///
/// # Examples
///
/// ```sway
/// use std::constants::ZERO_B256;
///
/// fn foo() {
/// let address = Address::from(ZERO_B256);
/// }
/// ```
fn from(bits: b256) -> Address {
Address { value: bits }
}

/// Casts an `Address` to raw `b256` data.
///
/// # Returns
///
/// * [b256] - The underlying raw `b256` data of the `Address`.
///
/// # Examples
///
/// ```sway
/// use std::constants::ZERO_B256;
///
/// fn foo() {
/// let address = Address::from(ZERO_B256);
/// let b256_data = address.into();
/// assert(b256_data == ZERO_B256);
/// }
/// ```
fn into(self) -> b256 {
self.value
}
Expand All @@ -34,25 +71,27 @@ impl Address {
/// Transfer `amount` coins of type `asset_id` and send them to
/// the Address.
///
/// ### Arguments
/// # Arguments
///
/// * `amount` - The amount of tokens to transfer.
/// * `asset_id` - The `AssetId` of the token to transfer.
/// * `amount`: [u64] - The amount of tokens to transfer.
/// * `asset_id`: [AssetId] - The `AssetId` of the token to transfer.
///
/// ### 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};
///
/// // replace the zero Address with your desired Address
/// let address = Address::from(ZERO_B256);
/// address.transfer(500, BASE_ASSET_ID)
/// fn foo() {
/// // replace the zero Address with your desired Address
/// let address = Address::from(ZERO_B256);
/// address.transfer(500, BASE_ASSET_ID)
/// }
/// ```
pub fn transfer(self, amount: u64, asset_id: AssetId) {
// maintain a manual index as we only have `while` loops in sway atm:
Expand Down Expand Up @@ -82,18 +121,20 @@ impl Address {
/// Mint `amount` coins of the current contract's `asset_id` and send them to
/// the Address.
///
/// ### Arguments
/// # Arguments
///
/// * `amount` - The amount of tokens to mint.
/// * `amount`: [u64] - The amount of tokens to mint.
///
/// ### Examples
/// # Examples
///
/// ```sway
/// use std::constants::ZERO_B256;
///
/// // replace the zero Address with your desired Address
/// let address = Address::from(ZERO_B256);
/// address.mint_to(500);
/// fn foo() {
/// // replace the zero Address with your desired Address
/// let address = Address::from(ZERO_B256);
/// address.mint_to(500);
/// }
/// ```
pub fn mint_to(self, amount: u64) {
asm(r1: amount) {
Expand Down
97 changes: 70 additions & 27 deletions sway-lib-std/src/contract_id.sw
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ use ::convert::From;

/// The `ContractId` type, a struct wrapper around the inner `b256` value.
pub struct ContractId {
/// The underlying raw `b256` data of the contract id.
value: b256,
}

Expand All @@ -16,10 +17,47 @@ impl core::ops::Eq for ContractId {

/// Functions for casting between the `b256` and `ContractId` types.
impl From<b256> for ContractId {
/// Casts raw `b256` data to a `ContractId`.
///
/// # Arguments
///
/// * `bits`: [b256] - The raw `b256` data to be casted.
///
/// # Returns
///
/// * [ContractId] - The newly created `ContractId` from the raw `b256`.
///
/// # Examples
///
/// ```sway
/// use std::constants::ZERO_B256;
///
/// fn foo() {
/// let contract_id = ContractId::from(ZERO_B256);
/// }
/// ```
fn from(bits: b256) -> ContractId {
ContractId { value: bits }
}


/// Casts a `ContractId` to raw `b256` data.
///
/// # Returns
///
/// * [b256] - The underlying raw `b256` data of the `ContractId`.
///
/// # Examples
///
/// ```sway
/// use std::constants::ZERO_B256;
///
/// fn foo() {
/// let contract_id = ContractId::from(ZERO_B256);
/// let b256_data = contract_id.into();
/// assert(b256_data == ZERO_B256);
/// }
/// ```
fn into(self) -> b256 {
self.value
}
Expand All @@ -29,30 +67,33 @@ impl ContractId {
/// UNCONDITIONAL transfer of `amount` coins of type `asset_id` to
/// the ContractId.
///
/// > **_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 Informations
///
/// ### Arguments
/// **_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.
///
/// * `amount` - The amount of tokens to transfer.
/// * `asset_id` - The `AssetId` of the token to transfer.
/// # Arguments
///
/// ### Reverts
/// * `amount`: [u64] - The amount of tokens to transfer.
/// * `asset_id`: [AssetId] - The `AssetId` of the token to transfer.
///
/// * If `amount` is greater than the contract balance for `asset_id`.
/// * If `amount` is equal to zero.
/// # Panics
///
/// ### Examples
/// * When `amount` is greater than the contract balance for `asset_id`.
/// * When `amount` is equal to zero.
///
/// # Examples
///
/// ```sway
/// use std::constants::{BASE_ASSET_ID, ZERO_B256};
///
/// // replace the zero ContractId with your desired ContractId
/// let contract_id = ContractId::from(ZERO_B256);
/// contract_id.transfer(500, BASE_ASSET_ID);
/// fn foo() {
/// // replace the zero ContractId with your desired ContractId
/// let contract_id = ContractId::from(ZERO_B256);
/// contract_id.transfer(500, BASE_ASSET_ID);
/// }
/// ```
pub fn transfer(self, amount: u64, asset_id: AssetId) {
asm(r1: amount, r2: asset_id.value, r3: self.value) {
Expand All @@ -65,25 +106,27 @@ impl ContractId {
/// 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
///
/// **_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.
///
/// ### 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.
///
/// ### Examples
/// # Examples
///
/// ```sway
/// use std::constants::ZERO_B256;
///
/// // replace the zero ContractId with your desired ContractId
/// let contract_id = ContractId::from(ZERO_B256);
/// contract_id.mint_to(500);
/// fn foo() {
/// // replace the zero ContractId with your desired ContractId
/// let contract_id = ContractId::from(ZERO_B256);
/// contract_id.mint_to(500);
/// }
/// ```
pub fn mint_to(self, amount: u64) {
asm(r1: amount) {
Expand Down
Loading

0 comments on commit 2a4f6fb

Please sign in to comment.