chore(iota-transaction-builder): Add crate documentation

crates/iota-transaction-builder/src/builder/mod.rs

@@ -363,6 +363,56 @@ impl<C, L> TransactionBuilder<C, L> {
     }
 
     /// Transfer objects to a recipient address.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use std::str::FromStr;
+    /// # use iota_types::{Address, Digest, Transaction, ObjectId, ObjectReference};
+    /// # use iota_transaction_builder::{TransactionBuilder, res};
+    ///
+    /// # #[tokio::main(flavor = "current_thread")]
+    /// # async fn main() -> eyre::Result<()> {
+    ///
+    /// let client = iota_graphql_client::Client::new_devnet();
+    /// let sender =
+    ///     Address::from_str("0x611830d3641a68f94a690dcc25d1f4b0dac948325ac18f6dd32564371735f32c")?;
+    ///
+    /// let mut builder = TransactionBuilder::new(sender).with_client(client);
+    ///
+    /// # builder
+    /// #     .split_coins(
+    /// #         ObjectId::from_str(
+    /// #             "0x0b0270ee9d27da0db09651e5f7338dfa32c7ee6441ccefa1f6e305735bcfc7ab",
+    /// #         )?,
+    /// #         [1000u64],
+    /// #     )
+    /// #     .name(("coin"));
+    ///
+    /// builder.transfer_objects(
+    ///     Address::from_str("0x0000a4984bd495d4346fa208ddff4f5d5e5ad48c21dec631ddebc99809f16900")?,
+    ///     (
+    ///         // ObjectIds can be passed when a client is provided
+    ///         ObjectId::from_str(
+    ///             "0xd04077fe3b6fad13b3d4ed0d535b7ca92afcac8f0f2a0e0925fb9f4f0b30c699",
+    ///         )?,
+    ///         // ObjectReferences are always allowed, though they must be correct
+    ///         ObjectReference {
+    ///             object_id: ObjectId::from_str(
+    ///                 "0x8ef4259fa2a3499826fa4b8aebeb1d8e478cf5397d05361c96438940b43d28c9",
+    ///             )?,
+    ///             digest: Digest::from_str("4jJMQScR4z5kK3vchvDEFYTiCkZPEYdvttpi3iTj1gEW")?,
+    ///             version: 435090179,
+    ///         },
+    ///         // The result of a previous command can also be used
+    ///         res("coin"),
+    ///     ),
+    /// );
+    ///
+    /// let txn: Transaction = builder.finish().await?;
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn transfer_objects<U: PTBArgumentList>(
         &mut self,
         recipient: Address,
@@ -486,6 +536,36 @@ impl<C, L> TransactionBuilder<C, L> {
 
 impl<L> TransactionBuilder<(), L> {
     /// Add a gas coin that will be consumed. Optional.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use std::str::FromStr;
+    /// # use iota_types::{Address, Digest, Transaction, ObjectId, ObjectReference};
+    /// # use iota_transaction_builder::{TransactionBuilder, res, unresolved};
+    ///
+    /// let sender =
+    ///     Address::from_str("0x611830d3641a68f94a690dcc25d1f4b0dac948325ac18f6dd32564371735f32c")?;
+    ///
+    /// let mut builder = TransactionBuilder::new(sender);
+    ///
+    /// let gas_coin = ObjectReference {
+    ///     object_id: ObjectId::from_str(
+    ///         "0x8ef4259fa2a3499826fa4b8aebeb1d8e478cf5397d05361c96438940b43d28c9",
+    ///     )?,
+    ///     digest: Digest::from_str("4jJMQScR4z5kK3vchvDEFYTiCkZPEYdvttpi3iTj1gEW")?,
+    ///     version: 435090179,
+    /// };
+    ///
+    /// builder
+    ///     .split_coins(unresolved::Argument::Gas, [1000u64])
+    ///     .gas(gas_coin)
+    ///     .gas_budget(1000000000)
+    ///     .gas_price(100);
+    ///
+    /// let txn: Transaction = builder.finish()?;
+    /// # Result::<_, eyre::Error>::Ok(())
+    /// ```
     pub fn gas(&mut self, obj_ref: ObjectReference) -> &mut Self {
         self.set_input(
             InputKind::Input(iota_types::Input::ImmutableOrOwned(obj_ref)),
@@ -564,7 +644,35 @@ impl<L> TransactionBuilder<Client, L> {
         &self.client
     }
 
-    /// Add a gas coin that will be consumed. Optional.
+    /// Add a gas coin that will be consumed. If no gas coins are provided, the
+    /// client will set a default list owned by the sender.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use std::str::FromStr;
+    /// # use iota_types::{Address, Digest, Transaction, ObjectId, ObjectReference};
+    /// # use iota_transaction_builder::{TransactionBuilder, res, unresolved};
+    ///
+    /// # #[tokio::main(flavor = "current_thread")]
+    /// # async fn main() -> eyre::Result<()> {
+    /// let client = iota_graphql_client::Client::new_devnet();
+    /// let sender =
+    ///     Address::from_str("0x611830d3641a68f94a690dcc25d1f4b0dac948325ac18f6dd32564371735f32c")?;
+    ///
+    /// let mut builder = TransactionBuilder::new(sender).with_client(client);
+    ///
+    /// let gas_coin =
+    ///     ObjectId::from_str("0xd04077fe3b6fad13b3d4ed0d535b7ca92afcac8f0f2a0e0925fb9f4f0b30c699")?;
+    ///
+    /// builder
+    ///     .split_coins(unresolved::Argument::Gas, [1000u64])
+    ///     .gas(gas_coin);
+    ///
+    /// let txn: Transaction = builder.finish().await?;
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn gas(&mut self, object_id: ObjectId) -> &mut Self {
         self.set_input(InputKind::ImmutableOrOwned(object_id), true);
         self

crates/iota-transaction-builder/src/builder/ptb_arguments.rs

@@ -277,7 +277,7 @@ impl PTBArgument for &Res {
         if let Some(arg) = ptb.named_results.get(&self.0) {
             *arg
         } else {
-            panic!("no command named `{}` exists", self.0)
+            panic!("no command result named `{}` exists", self.0)
         }
     }
 }