docs: add docs for starknet-accounts (#640)

Author: xJonathanLEI

starknet-accounts/src/account/declaration.rs

@@ -52,6 +52,10 @@ const QUERY_VERSION_THREE: Felt = Felt::from_raw([
 ]);
 
 impl<'a, A> DeclarationV2<'a, A> {
+    /// Constructs a new [`DeclarationV2`].
+    ///
+    /// Users would typically use [`declare_v2`](fn.declare_v2) on an [`Account`] instead of
+    /// directly calling this method.
     pub const fn new(
         contract_class: Arc<FlattenedSierraClass>,
         compiled_class_hash: Felt,
@@ -67,20 +71,25 @@ impl<'a, A> DeclarationV2<'a, A> {
         }
     }
 
+    /// Returns a new [`DeclarationV2`] with the `nonce`.
     pub fn nonce(self, nonce: Felt) -> Self {
         Self {
             nonce: Some(nonce),
             ..self
         }
     }
 
+    /// Returns a new [`DeclarationV2`] with the `max_fee`.
     pub fn max_fee(self, max_fee: Felt) -> Self {
         Self {
             max_fee: Some(max_fee),
             ..self
         }
     }
 
+    /// Returns a new [`DeclarationV2`] with the fee estimate multiplier. The multiplier is used
+    /// when transaction fee is not manually specified and must be fetched from a [`Provider`]
+    /// instead.
     pub fn fee_estimate_multiplier(self, fee_estimate_multiplier: f64) -> Self {
         Self {
             fee_estimate_multiplier,
@@ -110,6 +119,7 @@ impl<'a, A> DeclarationV2<'a, A>
 where
     A: ConnectedAccount + Sync,
 {
+    /// Estimates transaction fees from a [`Provider`].
     pub async fn estimate_fee(&self) -> Result<FeeEstimate, AccountError<A::SignError>> {
         // Resolves nonce
         let nonce = match self.nonce {
@@ -124,6 +134,8 @@ where
         self.estimate_fee_with_nonce(nonce).await
     }
 
+    /// Simulates the transaction from a [`Provider`]. Transaction validation and fee transfer can
+    /// be skipped.
     pub async fn simulate(
         &self,
         skip_validate: bool,
@@ -143,6 +155,7 @@ where
             .await
     }
 
+    /// Signs and broadcasts the transaction to the network.
     pub async fn send(&self) -> Result<DeclareTransactionResult, AccountError<A::SignError>> {
         self.prepare().await?.send().await
     }
@@ -275,6 +288,10 @@ where
 }
 
 impl<'a, A> DeclarationV3<'a, A> {
+    /// Constructs a new [`DeclarationV3`].
+    ///
+    /// Users would typically use [`declare_v3`](fn.declare_v3) on an [`Account`] instead of
+    /// directly calling this method.
     pub const fn new(
         contract_class: Arc<FlattenedSierraClass>,
         compiled_class_hash: Felt,
@@ -292,34 +309,43 @@ impl<'a, A> DeclarationV3<'a, A> {
         }
     }
 
+    /// Returns a new [`DeclarationV3`] with the `nonce`.
     pub fn nonce(self, nonce: Felt) -> Self {
         Self {
             nonce: Some(nonce),
             ..self
         }
     }
 
+    /// Returns a new [`DeclarationV3`] with the `gas`.
     pub fn gas(self, gas: u64) -> Self {
         Self {
             gas: Some(gas),
             ..self
         }
     }
 
+    /// Returns a new [`DeclarationV3`] with the `gas_price`.
     pub fn gas_price(self, gas_price: u128) -> Self {
         Self {
             gas_price: Some(gas_price),
             ..self
         }
     }
 
+    /// Returns a new [`DeclarationV3`] with the gas amount estimate multiplier.  The multiplier is
+    /// used when the gas amount is not manually specified and must be fetched from a [`Provider`]
+    /// instead.
     pub fn gas_estimate_multiplier(self, gas_estimate_multiplier: f64) -> Self {
         Self {
             gas_estimate_multiplier,
             ..self
         }
     }
 
+    /// Returns a new [`DeclarationV3`] with the gas price estimate multiplier.  The multiplier is
+    /// used when the gas price is not manually specified and must be fetched from a [`Provider`]
+    /// instead.
     pub fn gas_price_estimate_multiplier(self, gas_price_estimate_multiplier: f64) -> Self {
         Self {
             gas_price_estimate_multiplier,
@@ -351,6 +377,7 @@ impl<'a, A> DeclarationV3<'a, A>
 where
     A: ConnectedAccount + Sync,
 {
+    /// Estimates transaction fees from a [`Provider`].
     pub async fn estimate_fee(&self) -> Result<FeeEstimate, AccountError<A::SignError>> {
         // Resolves nonce
         let nonce = match self.nonce {
@@ -365,6 +392,8 @@ where
         self.estimate_fee_with_nonce(nonce).await
     }
 
+    /// Simulates the transaction from a [`Provider`]. Transaction validation and fee transfer can
+    /// be skipped.
     pub async fn simulate(
         &self,
         skip_validate: bool,
@@ -384,6 +413,7 @@ where
             .await
     }
 
+    /// Signs and broadcasts the transaction to the network.
     pub async fn send(&self) -> Result<DeclareTransactionResult, AccountError<A::SignError>> {
         self.prepare().await?.send().await
     }
@@ -570,6 +600,10 @@ where
 }
 
 impl<'a, A> LegacyDeclaration<'a, A> {
+    /// Constructs a new [`LegacyDeclaration`].
+    ///
+    /// Users would typically use [`declare_legacy`](fn.declare_legacy) on an [`Account`] instead of
+    /// directly calling this method.
     pub const fn new(contract_class: Arc<LegacyContractClass>, account: &'a A) -> Self {
         Self {
             account,
@@ -580,20 +614,25 @@ impl<'a, A> LegacyDeclaration<'a, A> {
         }
     }
 
+    /// Returns a new [`LegacyDeclaration`] with the `nonce`.
     pub fn nonce(self, nonce: Felt) -> Self {
         Self {
             nonce: Some(nonce),
             ..self
         }
     }
 
+    /// Returns a new [`LegacyDeclaration`] with the `max_fee`.
     pub fn max_fee(self, max_fee: Felt) -> Self {
         Self {
             max_fee: Some(max_fee),
             ..self
         }
     }
 
+    /// Returns a new [`LegacyDeclaration`] with the fee estimate multiplier. The multiplier is used
+    /// when transaction fee is not manually specified and must be fetched from a [`Provider`]
+    /// instead.
     pub fn fee_estimate_multiplier(self, fee_estimate_multiplier: f64) -> Self {
         Self {
             fee_estimate_multiplier,
@@ -623,6 +662,7 @@ impl<'a, A> LegacyDeclaration<'a, A>
 where
     A: ConnectedAccount + Sync,
 {
+    /// Estimates transaction fees from a [`Provider`].
     pub async fn estimate_fee(&self) -> Result<FeeEstimate, AccountError<A::SignError>> {
         // Resolves nonce
         let nonce = match self.nonce {
@@ -637,6 +677,8 @@ where
         self.estimate_fee_with_nonce(nonce).await
     }
 
+    /// Simulates the transaction from a [`Provider`]. Transaction validation and fee transfer can
+    /// be skipped.
     pub async fn simulate(
         &self,
         skip_validate: bool,
@@ -656,6 +698,7 @@ where
             .await
     }
 
+    /// Signs and broadcasts the transaction to the network.
     pub async fn send(&self) -> Result<DeclareTransactionResult, AccountError<A::SignError>> {
         self.prepare().await?.send().await
     }
@@ -787,6 +830,7 @@ where
 }
 
 impl RawDeclarationV2 {
+    /// Calculates transaction hash given `chain_id`, `address`, and `query_only`.
     pub fn transaction_hash(&self, chain_id: Felt, address: Felt, query_only: bool) -> Felt {
         compute_hash_on_elements(&[
             PREFIX_DECLARE,
@@ -805,24 +849,29 @@ impl RawDeclarationV2 {
         ])
     }
 
+    /// Gets a reference to the flattened Sierra (Cairo 1) class being declared.
     pub fn contract_class(&self) -> &FlattenedSierraClass {
         &self.contract_class
     }
 
+    /// Gets the CASM class hash corresponding to the Sierra class being declared.
     pub const fn compiled_class_hash(&self) -> Felt {
         self.compiled_class_hash
     }
 
+    /// Gets the `nonce` of the declaration request.
     pub const fn nonce(&self) -> Felt {
         self.nonce
     }
 
+    /// Gets the `max_fee` of the declaration request.
     pub const fn max_fee(&self) -> Felt {
         self.max_fee
     }
 }
 
 impl RawDeclarationV3 {
+    /// Calculates transaction hash given `chain_id`, `address`, and `query_only`.
     pub fn transaction_hash(&self, chain_id: Felt, address: Felt, query_only: bool) -> Felt {
         let mut hasher = PoseidonHasher::new();
 
@@ -876,28 +925,34 @@ impl RawDeclarationV3 {
         hasher.finalize()
     }
 
+    /// Gets a reference to the flattened Sierra (Cairo 1) class being declared.
     pub fn contract_class(&self) -> &FlattenedSierraClass {
         &self.contract_class
     }
 
+    /// Gets the CASM class hash corresponding to the Sierra class being declared.
     pub const fn compiled_class_hash(&self) -> Felt {
         self.compiled_class_hash
     }
 
+    /// Gets the `nonce` of the declaration request.
     pub const fn nonce(&self) -> Felt {
         self.nonce
     }
 
+    /// Gets the `gas` of the declaration request.
     pub const fn gas(&self) -> u64 {
         self.gas
     }
 
+    /// Gets the `gas_price` of the declaration request.
     pub const fn gas_price(&self) -> u128 {
         self.gas_price
     }
 }
 
 impl RawLegacyDeclaration {
+    /// Calculates transaction hash given `chain_id`, `address`, and `query_only`.
     pub fn transaction_hash(
         &self,
         chain_id: Felt,
@@ -920,14 +975,17 @@ impl RawLegacyDeclaration {
         ]))
     }
 
+    /// Gets a reference to the legacy (Cairo 0) class being declared.
     pub fn contract_class(&self) -> &LegacyContractClass {
         &self.contract_class
     }
 
+    /// Gets the `nonce` of the declaration request.
     pub const fn nonce(&self) -> Felt {
         self.nonce
     }
 
+    /// Gets the `max_fee` of the declaration request.
     pub const fn max_fee(&self) -> Felt {
         self.max_fee
     }
@@ -949,6 +1007,7 @@ impl<'a, A> PreparedDeclarationV2<'a, A>
 where
     A: ConnectedAccount,
 {
+    /// Signs and broadcasts the transaction to the network.
     pub async fn send(&self) -> Result<DeclareTransactionResult, AccountError<A::SignError>> {
         let tx_request = self.get_declare_request(false, false).await?;
         self.account
@@ -998,6 +1057,7 @@ impl<'a, A> PreparedDeclarationV3<'a, A>
 where
     A: ConnectedAccount,
 {
+    /// Signs and broadcasts the transaction to the network.
     pub async fn send(&self) -> Result<DeclareTransactionResult, AccountError<A::SignError>> {
         let tx_request = self.get_declare_request(false, false).await?;
         self.account
@@ -1066,6 +1126,7 @@ impl<'a, A> PreparedLegacyDeclaration<'a, A>
 where
     A: ConnectedAccount,
 {
+    /// Signs and broadcasts the transaction to the network.
     pub async fn send(&self) -> Result<DeclareTransactionResult, AccountError<A::SignError>> {
         let tx_request = self.get_declare_request(false, false).await?;
         self.account