Document SingleClaimableBalance structs

src/claimable_balances/all_claimable_balances_request.rs

@@ -4,7 +4,9 @@ use crate::{models::*, BuildQueryParametersExt};
 ///
 /// This structure is used to construct a query to retrieve a comprehensive list of claimable balances, which
 /// can be filtered by sponsor, asset, or claimant. Claimable balances are a feature of the Stellar network
-/// that allows users to create a balance of assets that can be claimed by another account.
+/// that allows users to create a balance of assets that can be claimed by another account. It adheres to the structure and parameters required 
+/// by the Horizon API for retrieving a 
+/// <a href="https://developers.stellar.org/api/horizon/resources/list-all-claimable-balances">list of claimable balances</a>.
 /// 
 /// # Usage
 ///

src/claimable_balances/mod.rs

@@ -80,15 +80,94 @@ pub mod all_claimable_balances_request;
 /// # }
 /// ```
 ///
-/// The `all_claimable_balances_response` module is an essential part of the SDK that allows developers 
-/// to work with claimable balances, supporting the building of applications that interact with 
-/// this Stellar network feature.
 pub mod all_claimable_balances_response;
 
+/// Provides the `SingleClaimableBalanceRequest` struct.
+///
+/// This module contains the `SingleClaimableBalanceRequest` struct, which is utilized to create 
+/// requests for retrieving information about a single claimable balance from the Stellar Horizon API. 
+/// It is specifically designed to query detailed data for a particular claimable balance identified by its ID.
+///
+/// The struct is intended to be used with the [`HorizonClient`](crate::horizon_client::HorizonClient) 
+/// to perform API calls and fetch detailed information about a specific claimable balance.
+///
+/// # Usage
+///
+/// To use this module, instantiate a `SingleClaimableBalanceRequest` and set the claimable balance ID.
+/// Then, pass this request to the [`HorizonClient::get_single_claimable_balance`](crate::horizon_client::HorizonClient::get_single_claimable_balance) method to execute the query.
+/// The method returns a `SingleClaimableBalanceResponse` with the detailed information.
+///
+/// # Example
+/// ```
+/// # use stellar_rust_sdk::claimable_balances::single_claimable_balance_request::SingleClaimableBalanceRequest;
+/// # use stellar_rust_sdk::horizon_client::HorizonClient;
+/// # use stellar_rust_sdk::models::Request;
+/// # 
+/// # async fn fetch_claimable_balance() -> Result<(), Box<dyn std::error::Error>> {
+/// #     let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org".to_string())?;
+/// let request = SingleClaimableBalanceRequest::new()
+///     .set_claimable_balance_id("00000000".to_string());  // Example claimable balance ID
+///
+/// let response = horizon_client.get_single_claimable_balance(&request).await?;
+/// // Process the response
+/// #     Ok(())
+/// # }
+/// ```
+///
 pub mod single_claimable_balance_request;
 
+/// Provides the `SingleClaimableBalanceResponse`.
+///
+/// This module contains structures representing the response received from the Horizon API 
+/// when querying a single claimable balance. The main structure, `SingleClaimableBalanceResponse`,
+/// is designed to convert the JSON response from the Horizon server into structured Rust objects.
+/// This allows for easier handling and utilization of claimable balance data within client applications.
+/// 
+/// For a detailed description of the response structure, refer to the 
+/// [Retrieve a Single Claimable Balance](https://developers.stellar.org/api/horizon/resources/retrieve-a-claimable-balance) 
+/// endpoint documentation on the Stellar Developer's site.
+///
+/// The structures in this module include serialization and deserialization capabilities to handle
+/// JSON data returned by the Horizon server. The `Getters` derive macro is used to provide 
+/// convenient getter methods for accessing fields of these structures.
+///
+/// # Usage
+///
+/// The response structures are primarily used internally by the `HorizonClient` when processing 
+/// responses from claimable balance-related API calls. The `SingleClaimableBalanceResponse` struct 
+/// is especially important as it is returned by the 
+/// [`HorizonClient::get_single_claimable_balance`](crate::horizon_client::HorizonClient::get_single_claimable_balance)
+/// method, providing a user-friendly way to access data of a single claimable balance.
+///
+/// # Example
+///
+/// ```
+/// # use stellar_rust_sdk::claimable_balances::prelude::{SingleClaimableBalanceRequest, SingleClaimableBalanceResponse};
+/// # use stellar_rust_sdk::horizon_client::HorizonClient;
+/// # use stellar_rust_sdk::models::Response;
+/// # 
+/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
+/// #    let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org".to_string())?;
+/// let claimable_balance_id = "123456789abcdefg".to_string();
+/// let request = SingleClaimableBalanceRequest::new()
+///     .set_claimable_balance_id(claimable_balance_id);
+///
+/// let response = horizon_client
+///     .get_single_claimable_balance(&request)
+///     .await;
+///
+/// // Access the details of the claimable balance
+/// if let Ok(balance_response) = response {
+///     println!("Balance Amount: {}", balance_response.amount());
+///     // Further processing...
+/// }
+/// #     Ok(())
+/// # }
+/// ```
+///
 pub mod single_claimable_balance_response;
 
+
 /// The base path for all claimable balance related endpoints in the Stellar Horizon API.
 ///
 /// This static variable holds the string slice that represents the common base path used in constructing

src/claimable_balances/single_claimable_balance_request.rs

@@ -1,22 +1,62 @@
 use crate::models::*;
 
+/// Represents the ID of a claimable balance.
 #[derive(Default, Clone)]
 pub struct ClaimableBalanceId(String);
+
+/// Represents the absence of a claimable balance ID.
 #[derive(Default, Clone)]
 pub struct NoClaimableBalanceId;
 
-/// SingleClaimableBalanceRequest is the struct that implements the type for the /claimable_balances endpoint to get a single claimable balance
-/// [More Details](https://developers.stellar.org/api/horizon/resources/retrieve-a-claimable-balance) "Single Claimable Balance")
+/// Represents a request to retrieve information about a single claimable balance from the Stellar Horizon API.
+///
+/// The `SingleClaimableBalanceRequest` struct is designed for querying detailed data for a specific 
+/// claimable balance, identified by its unique ID. It adheres to the structure and parameters required 
+/// by the Horizon API for retrieving a 
+/// <a href="https://developers.stellar.org/api/horizon/resources/retrieve-a-claimable-balance">single claimable balance</a>.
+///
+/// The struct is used in conjunction with the [`HorizonClient`](crate::horizon_client::HorizonClient) to 
+/// make API calls to the Horizon server and fetch the desired claimable balance information.
+///
+/// # Usage
+///
+/// To create a request, instantiate a `SingleClaimableBalanceRequest` and set the claimable balance ID 
+/// using `set_claimable_balance_id`. Then, pass the request object to the [`HorizonClient::get_single_claimable_balance`](crate::horizon_client::HorizonClient::get_single_claimable_balance)
+/// method to execute the query. The method returns a `SingleClaimableBalanceResponse` containing the details of the claimable balance.
+///
+/// # Example
+/// ```
+/// # use stellar_rust_sdk::claimable_balances::single_claimable_balance_request::SingleClaimableBalanceRequest;
+/// # use stellar_rust_sdk::horizon_client::HorizonClient;
+/// # use stellar_rust_sdk::models::Request;
+/// # 
+/// # async fn fetch_single_claimable_balance() -> Result<(), Box<dyn std::error::Error>> {
+/// #     let horizon_client = HorizonClient::new("https://horizon-testnet.stellar.org".to_string())?;
+/// let request = SingleClaimableBalanceRequest::new()
+///     .set_claimable_balance_id("00000000".to_string());  // Example claimable balance ID
+///
+/// let response = horizon_client.get_single_claimable_balance(&request).await?;
+/// // Process the response
+/// #     Ok(())
+/// # }
+/// ```
+/// 
 #[derive(Default)]
 pub struct SingleClaimableBalanceRequest<I> {
     claimable_balance_id: I,
 }
 
 impl SingleClaimableBalanceRequest<NoClaimableBalanceId> {
+    /// Creates a new `SingleClaimableBalanceRequest` with default parameters.
     pub fn new() -> Self {
         SingleClaimableBalanceRequest::default()
     }
 
+    /// Sets the claimable balance ID for the request.
+    ///
+    /// # Arguments
+    /// * `claimable_balance_id` - A `String` representing the claimable balance ID.
+    /// 
     pub fn set_claimable_balance_id(
         self,
         claimable_balance_id: String,

src/claimable_balances/single_claimable_balance_response.rs

@@ -6,100 +6,162 @@ use serde::Serialize;
 
 use crate::models::Response;
 
+/// Represents the response to a single claimable balance query in the Horizon API.
 #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)]
 #[serde(rename_all = "camelCase")]
 pub struct SingleClaimableBalanceResponse {
+    /// Links to related resources in the Horizon API response.
     #[serde(rename = "_links")]
     pub links: Links,
+
+    /// The unique identifier of the claimable balance.
     pub id: String,
+
+    /// The asset type of the claimable balance.
     pub asset: String,
+
+    /// The amount of the claimable balance.
     pub amount: String,
+
+    /// The account ID of the sponsor of the claimable balance.
     pub sponsor: String,
+
+    /// The ledger number in which the claimable balance was last modified.
     #[serde(rename = "last_modified_ledger")]
     pub last_modified_ledger: i64,
+
+    /// The timestamp when the claimable balance was last modified.
     #[serde(rename = "last_modified_time")]
     pub last_modified_time: String,
+
+    /// A list of claimants eligible to claim the balance.
     pub claimants: Vec<Claimant>,
+
+    /// Flags indicating special conditions of the claimable balance.
     pub flags: Flags,
+
+    /// A token used for paging through results.
     #[serde(rename = "paging_token")]
     pub paging_token: String,
 }
 
+/// Contains navigational links related to the single claimable balance response.
 #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)]
 #[serde(rename_all = "camelCase")]
 pub struct Links {
+    /// The link to the current claimable balance resource.
     #[serde(rename = "self")]
     pub self_field: SelfField,
+
+    /// Link to transactions related to the claimable balance.
     pub transactions: Transactions,
+
+    /// Link to operations related to the claimable balance.
     pub operations: Operations,
 }
 
+/// Represents a navigational link in the Horizon API response.
 #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)]
 #[serde(rename_all = "camelCase")]
 pub struct SelfField {
+    /// The URL of the link.
     pub href: String,
 }
 
+/// Represents a link to the transactions of a claimable balance.
 #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)]
 #[serde(rename_all = "camelCase")]
 pub struct Transactions {
+    /// The URL of the transactions link.
     pub href: String,
+
+    /// Indicates if the link is templated.
     pub templated: bool,
 }
 
+/// Represents a link to the operations of a claimable balance.
 #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)]
 #[serde(rename_all = "camelCase")]
 pub struct Operations {
+    /// The URL of the operations link.
     pub href: String,
+
+    /// Indicates if the link is templated.
     pub templated: bool,
 }
 
+/// Represents a claimant of a claimable balance.
 #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)]
 #[serde(rename_all = "camelCase")]
 pub struct Claimant {
+    /// The account ID of the claimant.
     pub destination: String,
+
+    /// Conditions that need to be met for the claimant to claim the balance.
     pub predicate: Predicate,
 }
 
+/// Represents conditions under which a claimable balance can be claimed.
 #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)]
 #[serde(rename_all = "camelCase")]
 pub struct Predicate {
+    /// Indicates if the claim is unconditional.
     pub unconditional: Option<bool>,
+
+    /// Conditions combined using the logical 'or' operation.
     pub or: Option<Vec<Or>>,
 }
 
+/// Represents an 'or' condition in a claimable balance's claim predicate.
 #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)]
 #[serde(rename_all = "camelCase")]
 pub struct Or {
+    /// Conditions combined using the logical 'and' operation.
     pub and: Option<Vec<And>>,
+
+    /// Specifies the absolute time before which the claim is valid.
     #[serde(rename = "abs_before")]
     pub abs_before: Option<String>,
+
+    /// The epoch time representation of `abs_before`.
     #[serde(rename = "abs_before_epoch")]
     pub abs_before_epoch: Option<String>,
 }
 
+/// Represents an 'and' condition in a claimable balance's claim predicate.
 #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)]
 #[serde(rename_all = "camelCase")]
 pub struct And {
+    /// A negation of a condition.
     pub not: Option<Not>,
+
+    /// Specifies the absolute time before which the claim is valid.
     #[serde(rename = "abs_before")]
     pub abs_before: Option<String>,
+
+    /// The epoch time representation of `abs_before`.
     #[serde(rename = "abs_before_epoch")]
     pub abs_before_epoch: Option<String>,
 }
 
+/// Represents a 'not' condition in a claimable balance's claim predicate.
 #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)]
 #[serde(rename_all = "camelCase")]
 pub struct Not {
+    /// Specifies the absolute time before which the claim is invalid.
     #[serde(rename = "abs_before")]
     pub abs_before: String,
+
+    /// The epoch time representation of `abs_before`.
     #[serde(rename = "abs_before_epoch")]
     pub abs_before_epoch: String,
 }
 
+/// Flags indicating special conditions of the claimable balance.
 #[derive(Default, Debug, Clone, Serialize, Deserialize, Getters)]
 #[serde(rename_all = "camelCase")]
 pub struct Flags {
+    /// Indicates if the clawback feature is enabled for the claimable balance.
     #[serde(rename = "clawback_enabled")]
     pub clawback_enabled: bool,
 }