feat(iota-transaction-builder): improve send_coins docs

Author: Thoralf-M

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

@@ -379,6 +379,42 @@ impl<C, L> TransactionBuilder<C, L> {
 
     /// Transfer some coins to a recipient address. If multiple coins are
     /// provided then they will be merged.
+    ///
+    /// The `amount` parameter specifies the quantity in NANOS, where 1 IOTA
+    /// equals 1_000_000_000 NANOS.
+    /// If `amount` is provided, that amount is split from the provided coins
+    /// and sent.
+    /// If `amount` is `None`, the entire coins are transferred.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use iota_graphql_client::Client;
+    /// use iota_transaction_builder::TransactionBuilder;
+    /// use iota_types::{Address, ObjectId};
+    ///
+    /// #[tokio::main(flavor = "current_thread")]
+    /// async fn main() -> eyre::Result<()> {
+    ///     let client = Client::new_devnet();
+    ///     let from_address = Address::from_hex(
+    ///         "0x611830d3641a68f94a690dcc25d1f4b0dac948325ac18f6dd32564371735f32c",
+    ///     )?;
+    ///     let to_address = Address::from_hex(
+    ///         "0x0000a4984bd495d4346fa208ddff4f5d5e5ad48c21dec631ddebc99809f16900",
+    ///     )?;
+    ///
+    ///     // This is a coin of type
+    ///     // 0x3358bea865960fea2a1c6844b6fc365f662463dd1821f619838eb2e606a53b6a::cert::CERT
+    ///     let coin = ObjectId::from_hex(
+    ///         "0x8ef4259fa2a3499826fa4b8aebeb1d8e478cf5397d05361c96438940b43d28c9",
+    ///     )?;
+    ///
+    ///     let mut builder = TransactionBuilder::new(from_address).with_client(client);
+    ///     builder.send_coins([coin], to_address, 50000000000u64);
+    ///     let txn = builder.finish().await?;
+    ///     Ok(())
+    /// }
+    /// ```
     pub fn send_coins<T: PTBArgumentList, U: PTBArgument>(
         &mut self,
         coins: T,