Update std-lib cryptographic functions to meet SRC-2 inline docs standard

sway-lib-std/src/ecr.sw

@@ -9,11 +9,36 @@ use ::result::Result::{self, *};
 
 /// The error type used when the `ec_recover` function fails.
 pub enum EcRecoverError {
+    /// The error varient used when the recover fails.
     UnrecoverablePublicKey: (),
 }
 
 /// Recover the public key derived from the private key used to sign a message.
 /// Returns a `Result` to let the caller choose an error handling strategy.
+///
+/// # Arguments
+///
+/// * `signature`: [B512] - The signature generated by signing over a message hash.
+/// * `msg_hash`: [b256] - The data which the was signed.
+///
+/// # Returns
+///
+/// * [Result<B512, EcRecoverError>] - The recovered public key or an error.
+///
+/// # Examples
+///
+/// ```sway
+/// use std::{erc::ec_recover, b512::B512};
+///
+/// fn foo() {
+///     let hi = 0xbd0c9b8792876713afa8bff383eebf31c43437823ed761cc3600d0016de5110c;
+///     let lo = 0x44ac566bd156b4fc71a4a4cb2655d3dd360c695edb17dc3b64d611e122fea23d;
+///     let msg_hash = 0xee45573606c96c98ba970ff7cf9511f1b8b25e6bcd52ced30b89df1e4a9c4323;
+///     let signature: B512 = B512::from((hi, lo));
+///     // A recovered public key pair.
+///     let public_key = ec_recover(signature, msg_hash).unwrap();
+/// }
+/// ```
 pub fn ec_recover(signature: B512, msg_hash: b256) -> Result<B512, EcRecoverError> {
     let public_key = B512::new();
     let was_error = asm(buffer: public_key.bytes, sig: signature.bytes, hash: msg_hash) {
@@ -30,6 +55,30 @@ pub fn ec_recover(signature: B512, msg_hash: b256) -> Result<B512, EcRecoverErro
 
 /// Recover the address derived from the private key used to sign a message.
 /// Returns a `Result` to let the caller choose an error handling strategy.
+///
+/// # Arguments
+///
+/// * `signature`: [B512] - The signature generated by signing over a message hash.
+/// * `msg_hash`: [b256] - The data which the was signed.
+///
+/// # Returns
+///
+/// * [Result<Address, EcRecoverError>] - The recovered Fuel address or an error.
+///
+/// # Examples
+///
+/// ```sway
+/// use std::{erc::ec_recover_address, b512::B512};
+///
+/// fn foo() {
+///     let hi = 0xbd0c9b8792876713afa8bff383eebf31c43437823ed761cc3600d0016de5110c;
+///     let lo = 0x44ac566bd156b4fc71a4a4cb2655d3dd360c695edb17dc3b64d611e122fea23d;
+///     let msg_hash = 0xee45573606c96c98ba970ff7cf9511f1b8b25e6bcd52ced30b89df1e4a9c4323;
+///     let signature: B512 = B512::from((hi, lo));
+///     // A recovered Fuel address.
+///     let result_address = ec_recover_address(signature, msg_hash).unwrap();
+/// }
+/// ```
 pub fn ec_recover_address(signature: B512, msg_hash: b256) -> Result<Address, EcRecoverError> {
     let pub_key_result = ec_recover(signature, msg_hash);
 

sway-lib-std/src/hash.sw

@@ -2,6 +2,25 @@
 library;
 
 /// Returns the `SHA-2-256` hash of `param`.
+///
+/// # Arguments
+///
+/// * `param`: [T] - The value to be hashed.
+///
+/// # Returns
+///
+/// * [b256] - The sha-256 hash of the value.
+///
+/// # Examples
+/// 
+/// ```sway
+/// use std::hash::sha256;
+///
+/// fn foo() {
+///     let result = sha256("Fuel");
+///     assert(result = 0xa80f942f4112036dfc2da86daf6d2ef6ede3164dd56d1000eb82fa87c992450f);
+/// }
+/// ```
 pub fn sha256<T>(param: T) -> b256 {
     let mut result_buffer: b256 = b256::min();
     if !__is_reference_type::<T>() {
@@ -27,6 +46,25 @@ pub fn sha256<T>(param: T) -> b256 {
 }
 
 /// Returns the `KECCAK-256` hash of `param`.
+///
+/// # Arguments
+///
+/// * `param`: [T] - The value to be hashed.
+///
+/// # Returns
+///
+/// * [b256] - The keccak-256 hash of the value.
+///
+/// # Examples
+/// 
+/// ```sway
+/// use std::hash::keccak256;
+///
+/// fn foo() {
+///     let result = keccak256("Fuel");
+///     assert(result = 0x4375c8bcdc904e5f51752581202ae9ae2bb6eddf8de05d5567d9a6b0ae4789ad);
+/// }
+/// ```
 pub fn keccak256<T>(param: T) -> b256 {
     let mut result_buffer: b256 = b256::min();
     if !__is_reference_type::<T>() {

sway-lib-std/src/message.sw

@@ -8,13 +8,28 @@ use ::revert::revert;
 
 /// Sends a message `msg_data` to `recipient` with a `coins` amount of the base asset.
 ///
+/// # Additional Information
+///
 /// Use `send_typed_message` instead of `send_message` if the message needs to be indexed.
 ///
-/// ### Arguments
+/// # Arguments
+///
+/// * `recipient`: [b256] - The address of the message recipient.
+/// * `msg_data`: [Bytes] - Arbitrary length message data.
+/// * `coins`: [u64] - Amount of base asset to send.
+///
+/// # Examples
 ///
-/// * `recipient` - The address of the message recipient.
-/// * `msg_data` - Arbitrary length message data.
-/// * `coins` - Amount of base asset to send.
+/// ```sway
+/// use std::{message::send_message, bytes::Bytes};
+/// 
+/// fn foo() {
+///     let recipient = 0xee45573606c96c98ba970ff7cf9511f1b8b25e6bcd52ced30b89df1e4a9c4323;
+///     let mut bytes = Bytes::new();
+///     bytes.push(5u8);
+///     send_message(recipient, bytes, 50);
+/// }
+/// ```
 pub fn send_message(recipient: b256, msg_data: Bytes, coins: u64) {
     let recipient_pointer = __addr_of(recipient);
     let mut size = 0;
@@ -33,13 +48,26 @@ pub fn send_message(recipient: b256, msg_data: Bytes, coins: u64) {
 
 /// Sends a message `msg_data` of type `T` to `recipient` with a `coins` amount of the base asset.
 ///
+/// # Additional Information
+///
 /// Use `send_typed_message` instead of `send_message` if the message needs to be indexed.
 ///
-/// ### Arguments
+/// # Arguments
+///
+/// * `recipient`: [b256] - The address of the message recipient.
+/// * `msg_data`: [T] - Message data of arbitrary type `T`.
+/// * `coins`: [u64] - Amount of base asset to send.
+///
+/// # Examples
 ///
-/// * `recipient` - The address of the message recipient.
-/// * `msg_data` - Message data of arbitrary type `T`.
-/// * `coins` - Amount of base asset to send.
+/// ```sway
+/// use std::message::send_typed_message;
+/// 
+/// fn foo() {
+///     let recipient = 0xee45573606c96c98ba970ff7cf9511f1b8b25e6bcd52ced30b89df1e4a9c4323;
+///     send_message(recipient, "Fuel is blazingly fast", 50);
+/// }
+/// ```
 pub fn send_typed_message<T>(recipient: b256, msg_data: T, coins: u64) {
     __smo(recipient, msg_data, coins);
 }

sway-lib-std/src/vm/evm/ecr.sw

@@ -10,6 +10,30 @@ use ::vm::evm::evm_address::EvmAddress;
 
 /// Recover the EVM address derived from the private key used to sign a message.
 /// Returns a `Result` to let the caller choose an error handling strategy.
+///
+/// # Arguments
+///
+/// * `signature`: [B512] - The signature generated by signing over a message hash.
+/// * `msg_hash`: [b256] - The data which the was signed.
+///
+/// # Returns
+///
+/// * [Result<EvmAddress, EcRecoverError>] - The recovered evm address or an error.
+///
+/// # Examples
+///
+/// ```sway
+/// use std::{vm::evm::ecr::ec_recover_evm_address, b512::B512};
+///
+/// fn foo() {
+///     let hi = 0xbd0c9b8792876713afa8bff383eebf31c43437823ed761cc3600d0016de5110c;
+///     let lo = 0x44ac566bd156b4fc71a4a4cb2655d3dd360c695edb17dc3b64d611e122fea23d;
+///     let msg_hash = 0xee45573606c96c98ba970ff7cf9511f1b8b25e6bcd52ced30b89df1e4a9c4323;
+///     let signature: B512 = B512::from((hi, lo));
+///     // A recovered evm address.
+///     let result_address = ec_recover_evm_address(signature, msg_hash).unwrap();
+/// }
+/// ```
 pub fn ec_recover_evm_address(
     signature: B512,
     msg_hash: b256,

sway-lib-std/src/vm/evm/evm_address.sw

@@ -6,6 +6,7 @@ use ::convert::From;
 
 /// The `EvmAddress` type, a struct wrapper around the inner `b256` value.
 pub struct EvmAddress {
+    /// The underlying evm address data.
     value: b256,
 }