docs(ICRC_Ledger): FI-1619: Add rustdoc to icrc-ledger-types (#3345)

Add rustdoc to the `icrc-ledger-types`.

packages/icrc-ledger-types/src/icrc/generic_metadata_value.rs

@@ -2,7 +2,12 @@ use candid::{CandidType, Deserialize, Int, Nat};
 use serde::Serialize;
 use serde_bytes::ByteBuf;
 
-/// Variant type for the `metadata` endpoint values.
+/// Variant type for the `icrc1_metadata` endpoint values. The corresponding metadata keys are
+/// arbitrary Unicode strings and must follow the pattern `<namespace>:<key>`, where `<namespace>`
+/// is a string not containing colons. The namespace `icrc1` is reserved for keys defined in the
+/// ICRC-1 standard. For more information, see the
+/// [documentation of Metadata in the ICRC-1 standard](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-1#metadata).
+/// Note that the `MetadataValue` type is a subset of the [`icrc_ledger_types::icrc::generic_value::ICRC3Value`] type.
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub enum MetadataValue {
     Nat(Nat),
@@ -12,6 +17,7 @@ pub enum MetadataValue {
 }
 
 impl MetadataValue {
+    /// Create a `(String, MetadataValue)` tuple for use in metadata maps.
     pub fn entry(key: impl ToString, val: impl Into<MetadataValue>) -> (String, Self) {
         (key.to_string(), val.into())
     }

packages/icrc-ledger-types/src/icrc/generic_value.rs

@@ -15,6 +15,7 @@ pub type Map = BTreeMap<String, Value>;
 pub type ICRC3Map = BTreeMap<String, ICRC3Value>;
 pub type Hash = [u8; 32];
 
+/// A value defined in [the ICRC-3 standard](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md#value).
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
 pub enum ICRC3Value {
     Blob(ByteBuf),
@@ -33,6 +34,7 @@ impl std::fmt::Display for ICRC3Value {
 }
 
 impl ICRC3Value {
+    /// Compute [the hash of an ICRC-3 value](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md#value).
     pub fn hash(self) -> Hash {
         // TODO(FI-1263): copy the value hash function to avoid cloning self
         Value::from(self).hash()

packages/icrc-ledger-types/src/icrc/mod.rs

@@ -1,3 +1,5 @@
+//! Types for ICRC standards.
+
 pub mod generic_metadata_value;
 pub mod generic_value;
 pub mod generic_value_predicate;

packages/icrc-ledger-types/src/icrc1/account.rs

@@ -15,7 +15,8 @@ pub type Subaccount = [u8; 32];
 
 pub const DEFAULT_SUBACCOUNT: &Subaccount = &[0; 32];
 
-// Account representation of ledgers supporting the ICRC1 standard
+/// [Account](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md#value)
+/// representation of ledgers supporting the ICRC-1 standard.
 #[derive(Serialize, CandidType, Deserialize, Clone, Debug, Copy, Encode, Decode)]
 pub struct Account {
     #[cbor(n(0), with = "icrc_cbor::principal")]
@@ -25,6 +26,8 @@ pub struct Account {
 }
 
 impl Account {
+    /// The effective subaccount of an account - the subaccount if it is set, otherwise the default
+    /// subaccount of all zeroes.
     #[inline]
     pub fn effective_subaccount(&self) -> &Subaccount {
         self.subaccount.as_ref().unwrap_or(DEFAULT_SUBACCOUNT)

packages/icrc-ledger-types/src/icrc1/mod.rs

@@ -1,2 +1,5 @@
+//! The [ICRC-1](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/README.md)
+//! token standard.
+
 pub mod account;
 pub mod transfer;

packages/icrc-ledger-types/src/icrc1/transfer.rs

@@ -7,6 +7,7 @@ use std::fmt;
 pub type NumTokens = Nat;
 pub type BlockIndex = Nat;
 
+/// The arguments for the [ICRC-1 `transfer`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/README.md#icrc1_transfer-) endpoint.
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct TransferArg {
     #[serde(default)]
@@ -21,6 +22,9 @@ pub struct TransferArg {
     pub amount: NumTokens,
 }
 
+/// The [`Memo`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/README.md#icrc1_transfer-)
+/// is an arbitrary blob that has no meaning to the ledger. The ledger SHOULD allow memos of at
+/// least 32 bytes in length.
 #[derive(
     Serialize, Deserialize, CandidType, Clone, Hash, Debug, PartialEq, Eq, PartialOrd, Ord, Default,
 )]
@@ -51,6 +55,9 @@ impl From<Memo> for ByteBuf {
     }
 }
 
+/// Errors defined for the
+/// [ICRC-1 `transfer`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/README.md#icrc1_transfer-)
+/// endpoint.
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub enum TransferError {
     BadFee { expected_fee: NumTokens },

packages/icrc-ledger-types/src/icrc2/allowance.rs

@@ -3,12 +3,18 @@ use serde::Serialize;
 
 use super::super::icrc1::account::Account;
 
+/// The arguments for the
+/// [ICRC-2 `allowance`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_allowance)
+/// endpoint.
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct AllowanceArgs {
     pub account: Account,
     pub spender: Account,
 }
 
+/// The `Allowance` response type for the
+/// [ICRC-2 `allowance`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_allowance)
+/// endpoint.
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct Allowance {
     pub allowance: Nat,

packages/icrc-ledger-types/src/icrc2/approve.rs

@@ -5,6 +5,9 @@ use std::fmt;
 use super::super::icrc1::account::{Account, Subaccount};
 use super::super::icrc1::transfer::Memo;
 
+/// The arguments for the
+/// [ICRC-2 `approve`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_approve)
+/// endpoint.
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct ApproveArgs {
     #[serde(default)]
@@ -23,6 +26,9 @@ pub struct ApproveArgs {
     pub created_at_time: Option<u64>,
 }
 
+/// The error return type for the
+/// [ICRC-2 `approve`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_approve)
+/// endpoint.
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub enum ApproveError {
     BadFee { expected_fee: Nat },

packages/icrc-ledger-types/src/icrc2/mod.rs

@@ -1,3 +1,5 @@
+//! The [ICRC-2](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md)
+//! Approve and Transfer From standard.
 pub mod allowance;
 pub mod approve;
 pub mod transfer_from;

packages/icrc-ledger-types/src/icrc2/transfer_from.rs

@@ -5,6 +5,9 @@ use std::fmt;
 use super::super::icrc1::account::{Account, Subaccount};
 use super::super::icrc1::transfer::Memo;
 
+/// The arguments for the
+/// [ICRC-2 `transfer_from`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_transfer_from)
+/// endpoint.
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct TransferFromArgs {
     #[serde(default)]
@@ -20,6 +23,9 @@ pub struct TransferFromArgs {
     pub created_at_time: Option<u64>,
 }
 
+/// The error return type for the
+/// [ICRC-2 `transfer_from`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_transfer_from)
+/// endpoint.
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub enum TransferFromError {
     BadFee { expected_fee: Nat },

packages/icrc-ledger-types/src/icrc21/mod.rs

@@ -1,3 +1,6 @@
+//! The [ICRC-21](https://github.com/dfinity/wg-identity-authentication/blob/main/topics/ICRC-21/icrc_21_consent_msg.md)
+//! Canister Call Consent Messages standard.
+
 pub mod errors;
 pub mod lib;
 pub mod requests;

packages/icrc-ledger-types/src/icrc3/archive.rs

@@ -8,13 +8,21 @@ use candid::{CandidType, Deserialize, Nat, Principal};
 use serde::Serialize;
 use std::marker::PhantomData;
 
+/// Deprecated. The information in the `ArchivedRange` struct is returned as part of the return value
+/// of [`crate::icrc3::blocks::GetBlocksResult`] from the
+/// [`icrc3_get_blocks`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md)
+/// endpoint.
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct ArchivedRange<Callback> {
     pub start: Nat,
     pub length: Nat,
     pub callback: Callback,
 }
 
+/// Details on the callback function using which archived blocks can be retrieved. Returned as part
+/// of [`crate::icrc3::blocks::GetBlocksResult`] from the
+/// [`icrc3_get_blocks`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md)
+/// endpoint.
 #[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(try_from = "candid::types::reference::Func")]
 pub struct QueryArchiveFn<Input: CandidType, Output: CandidType> {
@@ -108,6 +116,7 @@ impl<Input: CandidType, Output: CandidType> CandidType for QueryArchiveFn<Input,
     }
 }
 
+/// Deprecated: Use `ICRC3ArchiveInfo`.
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct ArchiveInfo {
     pub canister_id: Principal,
@@ -117,6 +126,9 @@ pub struct ArchiveInfo {
 pub type QueryBlockArchiveFn = QueryArchiveFn<GetBlocksRequest, BlockRange>;
 pub type QueryTxArchiveFn = QueryArchiveFn<GetTransactionsRequest, TransactionRange>;
 
+/// The argument for the
+/// [`icrc3_get_archives`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md)
+/// endpoint.
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct GetArchivesArgs {
     // The last archive seen by the client.
@@ -126,6 +138,9 @@ pub struct GetArchivesArgs {
     pub from: Option<Principal>,
 }
 
+/// The information returned as part of the return value for the
+/// [`icrc3_get_archives`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md)
+/// endpoint.
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct ICRC3ArchiveInfo {
     // The id of the archive
@@ -138,4 +153,7 @@ pub struct ICRC3ArchiveInfo {
     pub end: Nat,
 }
 
+/// The return value for the
+/// [`icrc3_get_archives`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md)
+/// endpoint.
 pub type GetArchivesResult = Vec<ICRC3ArchiveInfo>;

packages/icrc-ledger-types/src/icrc3/blocks.rs

@@ -8,7 +8,7 @@ use serde_bytes::ByteBuf;
 
 use super::archive::QueryArchiveFn;
 
-/// Deprecated, use `ICRC3GenericBlock` instead
+/// Deprecated, use [`ICRC3GenericBlock`] instead
 pub type GenericBlock = Value;
 pub type ICRC3GenericBlock = ICRC3Value;
 
@@ -22,31 +22,40 @@ pub struct GetBlocksResponse {
     pub archived_blocks: Vec<ArchivedRange<QueryBlockArchiveFn>>,
 }
 
+/// A block with an ID. Returned as part of [`GetBlocksResult`].
 #[derive(Debug, CandidType, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub struct BlockWithId {
     pub id: Nat,
     pub block: ICRC3GenericBlock,
 }
 
+/// Information about where to find archived blocks. Returned as part of [`GetBlocksResult`].
 #[derive(Debug, CandidType, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub struct ArchivedBlocks {
     pub args: Vec<GetBlocksRequest>,
     pub callback: QueryArchiveFn<Vec<GetBlocksRequest>, GetBlocksResult>,
 }
 
+/// The result type for the
+/// [ICRC-3 `icrc3_get_blocks`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md#icrc3_get_blocks)
+/// endpoint.
 #[derive(Debug, CandidType, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub struct GetBlocksResult {
     pub log_length: Nat,
     pub blocks: Vec<BlockWithId>,
     pub archived_blocks: Vec<ArchivedBlocks>,
 }
 
+/// The arguments for the
+/// [ICRC-3 `icrc3_get_blocks`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md#icrc3_get_blocks)
+/// endpoint.
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
 pub struct GetBlocksRequest {
     pub start: BlockIndex,
     pub length: Nat,
 }
 
+/// The return type for the deprecated `get_blocks` endpoint of the archive canister.
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct BlockRange {
     pub blocks: Vec<GenericBlock>,
@@ -81,12 +90,18 @@ pub struct DataCertificate {
     pub hash_tree: serde_bytes::ByteBuf,
 }
 
+/// The data certificate returned from the
+/// [ICRC-3 `icrc3_get_tip_certificate`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md#icrc3_get_tip_certificate)
+/// endpoint.
 #[derive(Debug, CandidType, Serialize, Deserialize)]
 pub struct ICRC3DataCertificate {
     pub certificate: serde_bytes::ByteBuf,
     pub hash_tree: serde_bytes::ByteBuf,
 }
 
+/// The return type of the
+/// [ICRC-3 `icrc3_supported_block_types`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md#icrc3_supported_block_types)
+/// endpoint.
 #[derive(Debug, CandidType, Serialize, Deserialize)]
 pub struct SupportedBlockType {
     pub block_type: String,

packages/icrc-ledger-types/src/icrc3/mod.rs

@@ -1,3 +1,6 @@
+//! The [ICRC-3](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md)
+//! Block Log standard.
+
 pub mod archive;
 pub mod blocks;
 pub mod schema;

packages/icrc-ledger-types/src/icrc3/schema.rs

@@ -8,6 +8,7 @@ use crate::icrc::{
     },
 };
 
+/// Validate if a block is compatible with the ICRC-3 schema.
 // TODO(FI-1241): make it compatible with the final ICRC-3 schema
 pub fn validate(block: &Value) -> Result<(), ValuePredicateFailures> {
     use ItemRequirement::*;

packages/icrc-ledger-types/src/icrc3/transactions.rs

@@ -113,6 +113,9 @@ impl Transaction {
     }
 }
 
+/// Deprecated. Use [`GetBlocksResponse`] returned from the
+/// [`icrc3_get_blocks`](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-3/README.md)
+/// endpoint instead.
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct GetTransactionsResponse {
     pub log_length: Nat,
@@ -121,6 +124,7 @@ pub struct GetTransactionsResponse {
     pub archived_transactions: Vec<ArchivedRange<QueryTxArchiveFn>>,
 }
 
+/// Deprecated. Use Vec<[`ICRC3GenericBlock`]> instead
 #[derive(CandidType, Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct TransactionRange {
     pub transactions: Vec<Transaction>,

packages/icrc-ledger-types/src/lib.rs

@@ -1,3 +1,5 @@
+//! A library of types to communicate with a ledger canister that implements ICRC standards.
+
 pub mod icrc;
 pub mod icrc1;
 pub mod icrc2;