Sort forc-doc links alphabetically, add std-lib docs definitions (Fue…

…lLabs#4465)

## Description

This PR sorts forc doc links in alphabetical order and adds some missing
definitions to the std-lib docs.

Close FuelLabs#3995 

## 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).
- [ ] 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: Sophie Dankel <[email protected]>

forc-plugins/forc-doc/src/render/link.rs

@@ -23,9 +23,28 @@ pub(crate) struct DocLinks {
 }
 impl Renderable for DocLinks {
     fn render(self, _render_plan: RenderPlan) -> Result<Box<dyn RenderBox>> {
+        let mut links_vec = Vec::new();
+        // sort the doc links alphabetically
+        // for the AllDoc page, sort based on the module prefix
+        match self.style {
+            DocStyle::AllDoc(_) => {
+                for (block_title, mut doc_link) in self.links {
+                    doc_link.sort_by(|a, b| {
+                        a.module_info.module_prefixes[1].cmp(&b.module_info.module_prefixes[1])
+                    });
+                    links_vec.push((block_title, doc_link));
+                }
+            }
+            _ => {
+                for (block_title, mut doc_link) in self.links {
+                    doc_link.sort();
+                    links_vec.push((block_title, doc_link));
+                }
+            }
+        }
         let doc_links = match self.style {
             DocStyle::AllDoc(_) => box_html! {
-                @ for (title, list_items) in self.links {
+                @ for (title, list_items) in links_vec {
                     @ if !list_items.is_empty() {
                         h2(id=format!("{}", title.html_title_string())) { : title.as_str(); }
                         div(class="item-table") {
@@ -56,7 +75,7 @@ impl Renderable for DocLinks {
             .into_string()
             .unwrap(),
             DocStyle::ProjectIndex(_) => box_html! {
-                @ for (title, list_items) in self.links {
+                @ for (title, list_items) in links_vec {
                     @ if !list_items.is_empty() {
                         h2(id=format!("{}", title.html_title_string())) { : title.as_str(); }
                         div(class="item-table") {
@@ -91,7 +110,7 @@ impl Renderable for DocLinks {
             .into_string()
             .unwrap(),
             _ => box_html! {
-                @ for (title, list_items) in self.links {
+                @ for (title, list_items) in links_vec {
                     @ if !list_items.is_empty() {
                         h2(id=format!("{}", title.html_title_string())) { : title.as_str(); }
                         div(class="item-table") {

sway-lib-std/src/assert.sw

@@ -1,3 +1,4 @@
+//! Functions to assert a given condition.
 library;
 
 use ::logging::log;

sway-lib-std/src/auth.sw

@@ -8,6 +8,7 @@ use ::option::Option;
 use ::result::Result;
 use ::inputs::{Input, input_count, input_owner, input_type};
 
+/// The error type used when an `Identity` cannot be determined.
 pub enum AuthError {
     InputsNotAllOwnedBySameAddress: (),
 }

sway-lib-std/src/block.sw

@@ -9,12 +9,12 @@ pub fn height() -> u64 {
     }
 }
 
-/// Get the timestamp of the current block.
+/// Get the TAI64 timestamp of the current block.
 pub fn timestamp() -> u64 {
     timestamp_of_block(height())
 }
 
-/// Get the timestamp of a block at a given `block_height`.
+/// Get the TAI64 timestamp of a block at a given `block_height`.
 pub fn timestamp_of_block(block_height: u64) -> u64 {
     asm(timestamp, height: block_height) {
         time timestamp height;

sway-lib-std/src/bytes.sw

@@ -50,6 +50,7 @@ impl RawBytes {
     }
 }
 
+/// A type used to represent raw bytes.
 pub struct Bytes {
     buf: RawBytes,
     len: u64,

sway-lib-std/src/constants.sw

@@ -1,6 +1,10 @@
+//! Base asset and zero address constants.
 library;
 
 use ::contract_id::ContractId;
 
+/// The `BASE_ASSET_ID` represents the base asset of a chain.
+/// This is currently hard coded as a zero address, but will be configurable in the future.
 pub const BASE_ASSET_ID = ContractId::from(ZERO_B256);
+/// A B256 type zero address.
 pub const ZERO_B256 = 0x0000000000000000000000000000000000000000000000000000000000000000;

sway-lib-std/src/context.sw

@@ -10,7 +10,7 @@ pub fn this_balance(asset_id: ContractId) -> u64 {
     balance_of(asset_id, contract_id())
 }
 
-/// Get the balance of coin `asset_id` for for the contract at 'target'.
+/// Get the balance of coin `asset_id` for the contract at 'target'.
 pub fn balance_of(asset_id: ContractId, target: ContractId) -> u64 {
     asm(balance, token: asset_id.value, id: target.value) {
         bal balance token id;

sway-lib-std/src/ecr.sw

@@ -1,3 +1,4 @@
+//! Helper functions to verify signatures.
 library;
 
 use ::address::Address;
@@ -6,6 +7,7 @@ use ::registers::error;
 use ::hash::sha256;
 use ::result::Result;
 
+/// The error type used when the `ec_recover` function fails.
 pub enum EcRecoverError {
     UnrecoverablePublicKey: (),
 }

sway-lib-std/src/experimental.sw

@@ -1,3 +1,4 @@
+//! Experimental types and functions.
 library;
 
 mod r#storage;

sway-lib-std/src/experimental/storage.sw

@@ -1,3 +1,4 @@
+//! Experimental storage types.
 library;
 
 use ::alloc::{alloc, realloc_bytes};

sway-lib-std/src/external.sw

@@ -1,3 +1,4 @@
+//! Functions to work with external contracts.
 library;
 
 use ::constants::ZERO_B256;

sway-lib-std/src/hash.sw

@@ -1,3 +1,4 @@
+//! Utility functions for cryptographic hashing.
 library;
 
 /// Returns the `SHA-2-256` hash of `param`.

sway-lib-std/src/identity.sw

@@ -5,6 +5,7 @@ library;
 use ::address::Address;
 use ::contract_id::ContractId;
 
+/// The `Identity` type: either an `Address` or a `ContractId`.
 // ANCHOR: docs_identity
 pub enum Identity {
     Address: Address,

sway-lib-std/src/inputs.sw

@@ -59,6 +59,7 @@ pub const GTF_INPUT_MESSAGE_DATA = 0x11D;
 pub const GTF_INPUT_MESSAGE_PREDICATE = 0x11E;
 pub const GTF_INPUT_MESSAGE_PREDICATE_DATA = 0x11F;
 
+/// The input type for a transaction.
 pub enum Input {
     Coin: (),
     Contract: (),

sway-lib-std/src/low_level_call.sw

@@ -1,3 +1,4 @@
+//! Utilities to help with low level calls.
 library;
 
 use ::assert::assert;
@@ -7,6 +8,7 @@ use ::option::Option;
 use ::revert::require;
 use ::vec::Vec;
 
+/// A struct representing the call parameters of a function call.
 pub struct CallParams {
     coins: u64,
     asset_id: ContractId,

sway-lib-std/src/math.sw

@@ -1,5 +1,7 @@
+//! Utilities for common math operations.
 library;
 
+/// Calculates the square root.
 pub trait Root {
     fn sqrt(self) -> Self;
 }
@@ -44,6 +46,7 @@ impl Root for u8 {
     }
 }
 
+/// Calculates a number to a given power.
 pub trait Power {
     fn pow(self, exponent: Self) -> Self;
 }
@@ -84,13 +87,14 @@ impl Power for u8 {
     }
 }
 
-// Trait for exponential functions
-// Should exist for UFP64, UFP128 and their signed versions
+/// Trait for exponential functions.
+/// This should exist for UFP64, UFP128 and their signed versions.
 pub trait Exponent {
     // exponential function: e ^ exponent
     fn exp(exponent: Self) -> Self;
 }
 
+/// Calculates the log with a given base.
 pub trait Logarithm {
     fn log(self, base: Self) -> Self;
 }
@@ -131,6 +135,7 @@ impl Logarithm for u8 {
     }
 }
 
+/// Calculates the binary log.
 pub trait BinaryLogarithm {
     fn log2(self) -> Self;
 }

sway-lib-std/src/message.sw

@@ -1,3 +1,4 @@
+//! Helper functions to sign and send messages.
 library;
 
 use ::alloc::alloc_bytes;

sway-lib-std/src/option.sw

@@ -1,4 +1,4 @@
-//! Optional values.
+//! A type for optional values.
 //!
 //! Type `Option` represents an optional value: every `Option`
 //! is either `Some` and contains a value, or `None`, and
@@ -78,7 +78,7 @@ use ::result::Result;
 use ::revert::revert;
 
 // ANCHOR: docs_option
-/// `Option` is a type that represents an optional value.
+/// A type that represents an optional value, either `Some(val)` or `None`.
 pub enum Option<T> {
     /// No value.
     None: (),

sway-lib-std/src/outputs.sw

@@ -27,6 +27,8 @@ pub const GTF_OUTPUT_MESSAGE_AMOUNT = 0x209;
 
 // pub const GTF_OUTPUT_CONTRACT_CREATED_CONTRACT_ID = 0x20A;
 // pub const GTF_OUTPUT_CONTRACT_CREATED_STATE_ROOT = 0x20B;
+
+/// The output type for a transaction.
 pub enum Output {
     Coin: (),
     Contract: (),

sway-lib-std/src/revert.sw

@@ -1,11 +1,12 @@
+//! Functions to panic or revert with a given error code.
 library;
 
 use ::logging::log;
 use ::error_signals::FAILED_REQUIRE_SIGNAL;
 
-/// Context-dependent:
-/// Will panic if used in a predicate.
-/// Will revert if used in a contract.
+/// Will either panic or revert with a given number depending on the context.
+/// If used in a predicate, it will panic.
+/// If used in a contract, it will revert.
 ///
 /// ### Arguments
 ///

sway-lib-std/src/storage.sw

@@ -1,3 +1,4 @@
+//! Contract storage utilities.
 library;
 
 use ::alloc::{alloc, alloc_bytes, realloc_bytes};
@@ -239,6 +240,7 @@ pub fn clear_slice(key: b256) -> bool {
     __state_clear(sha256(key), number_of_slots)
 }
 
+/// A general way to persistently store heap types.
 pub trait StorableSlice<T> {
     #[storage(write)]
     fn store(self, argument: T);
@@ -1046,6 +1048,7 @@ impl<V> StorageVec<V> {
     }
 }
 
+/// A persistent storage type to store a collection of tightly packed bytes.
 pub struct StorageBytes {}
 
 impl StorableSlice<Bytes> for StorageBytes {

sway-lib-std/src/tx.sw

@@ -40,6 +40,7 @@ pub const GTF_CREATE_WITNESS_AT_INDEX = 0x01D;
 pub const GTF_WITNESS_DATA_LENGTH = 0x301;
 pub const GTF_WITNESS_DATA = 0x302;
 
+/// A transaction type.
 pub enum Transaction {
     Script: (),
     Create: (),
@@ -109,7 +110,7 @@ pub fn tx_witnesses_count() -> u64 {
     }
 }
 
-// Get a pointer to the witness at index `index` for either `tx_type`
+/// Get a pointer to the witness at index `index` for either `tx_type`
 /// (transaction-script or transaction-create).
 pub fn tx_witness_pointer(_index: u64) -> u64 {
     match tx_type() {
@@ -118,12 +119,12 @@ pub fn tx_witness_pointer(_index: u64) -> u64 {
     }
 }
 
-// Get the length of the witness data at `index`.
+/// Get the length of the witness data at `index`.
 pub fn tx_witness_data_length(index: u64) -> u64 {
     __gtf::<u64>(index, GTF_WITNESS_DATA_LENGTH)
 }
 
-// Get the witness data at `index`.
+/// Get the witness data at `index`.
 pub fn tx_witness_data<T>(index: u64) -> T {
     __gtf::<raw_ptr>(index, GTF_WITNESS_DATA).read::<T>()
 }

sway-lib-std/src/u128.sw

@@ -1,3 +1,4 @@
+//! A 128-bit unsigned integer type.
 library;
 
 use ::assert::assert;
@@ -13,6 +14,7 @@ pub struct U128 {
     lower: u64,
 }
 
+/// The error type used for `u128` type errors.
 pub enum U128Error {
     LossOfPrecision: (),
 }

sway-lib-std/src/u256.sw

@@ -1,3 +1,4 @@
+//! A 256-bit unsigned integer type.
 library;
 
 use ::assert::assert;
@@ -30,6 +31,7 @@ pub struct U256 {
     d: u64,
 }
 
+/// The error type used for `u256` type errors.
 pub enum U256Error {
     LossOfPrecision: (),
 }

sway-lib-std/src/vec.sw

@@ -1,3 +1,4 @@
+//! A vector type for dynamically sized arrays outside of storage.
 library;
 
 use ::alloc::{alloc, realloc};

sway-lib-std/src/vm.sw

@@ -1,3 +1,4 @@
+//! VM-specific utilities.
 library;
 
 mod evm;

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

@@ -1,3 +1,4 @@
+//! EVM-specific utilities.
 library;
 
 mod evm_address;

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

@@ -1,3 +1,4 @@
+//! Helper functions to verify EVM signatures.
 library;
 
 use ::b512::B512;

sway-lsp/tests/lib.rs

@@ -824,7 +824,7 @@ async fn go_to_definition_for_paths() {
         req_uri: &uri,
         req_line: 24,
         req_char: 31,
-        def_line: 5,
+        def_line: 9,
         def_start_char: 10,
         def_end_char: 19,
         def_path: "sway-lib-std/src/constants.sw",