From aafc8ec1b42dc3ee093e0f4a5b6042cae1abee2a Mon Sep 17 00:00:00 2001 From: Kevin Pease Date: Wed, 22 May 2024 14:13:20 +0200 Subject: [PATCH] Add documentation and fix minor details --- stellar_rust_sdk/src/horizon_client.rs | 49 +++++++++++++++++-- .../transactions/all_transactions_request.rs | 36 ++++++++++++-- stellar_rust_sdk/src/transactions/mod.rs | 16 ++++-- stellar_rust_sdk/src/transactions/response.rs | 6 ++- 4 files changed, 96 insertions(+), 11 deletions(-) diff --git a/stellar_rust_sdk/src/horizon_client.rs b/stellar_rust_sdk/src/horizon_client.rs index ca51619..407ca32 100644 --- a/stellar_rust_sdk/src/horizon_client.rs +++ b/stellar_rust_sdk/src/horizon_client.rs @@ -1432,15 +1432,58 @@ impl HorizonClient { self.get::(request).await } - // TODO: Documentation + + /// Retrieves a list of all transactions from the Horizon server. + /// + /// This asynchronous method fetches a list of all transactions from the Horizon server. + /// It requires an [`AllTransactionsRequest`] to specify the optional query parameters. + /// + /// # Arguments + /// * `request` - A reference to an [`AllTransactionsRequest`] instance, containing the + /// parameters for the transactions request. + /// + /// # Returns + /// + /// On successful execution, returns a `Result` containing an [`AllTransactionsResponse`], which includes + /// the list of all transactions obtained from the Horizon server. If the request fails, it returns an error within `Result`. + /// + /// # Usage + /// To use this method, create an instance of [`AllTransactionsRequest`] and set any desired + /// filters or parameters. + /// + /// ``` + /// # use stellar_rs::transactions::prelude::*; + /// # use stellar_rs::models::Request; + /// # use stellar_rs::horizon_client::HorizonClient; + /// # use stellar_rust_sdk_derive::Pagination; + /// # use stellar_rs::Paginatable; + /// # + /// # async fn example() -> Result<(), Box> { + /// # let base_url = "https://horizon-testnet.stellar.org".to_string(); + /// # let horizon_client = HorizonClient::new(base_url) + /// # .expect("Failed to create Horizon Client"); + /// let request = AllTransactionsRequest::new() + /// .set_include_failed(true).unwrap(); + /// + /// let response = horizon_client.get_all_transactions(&request).await; + /// + /// // Access the transactions + /// if let Ok(transactions_response) = response { + /// for transaction in transactions_response.embedded().records() { + /// println!("Transaction ID: {}", transaction.id()); + /// // Further processing... + /// } + /// } + /// # Ok({}) + /// # } + /// ``` + /// pub async fn get_all_transactions( &self, request: &AllTransactionsRequest, ) -> Result { self.get::(request).await } - - } /// Handles the response received from an HTTP request made to the Horizon server. diff --git a/stellar_rust_sdk/src/transactions/all_transactions_request.rs b/stellar_rust_sdk/src/transactions/all_transactions_request.rs index 3cc505b..d7b18f5 100644 --- a/stellar_rust_sdk/src/transactions/all_transactions_request.rs +++ b/stellar_rust_sdk/src/transactions/all_transactions_request.rs @@ -2,7 +2,35 @@ use crate::{models::*, BuildQueryParametersExt}; use stellar_rust_sdk_derive::Pagination; use crate::Paginatable; -// TODO: Documentation +/// Represents a request to list all transactions from the Stellar Horizon API. +/// +/// This structure is used to construct a query to retrieve a comprehensive list of transactions, which +/// can be filtered by setting `include_failed`. It adheres to the structure and parameters required +/// by the Horizon API for retrieving a +/// list of all transactions. +/// +/// # Usage +/// +/// Create an instance of this struct and set the desired query parameters to filter the list of transactions. +/// Pass this request object to the [`HorizonClient::get_all_transactions`](crate::horizon_client::HorizonClient::get_all_transactions) +/// method to fetch the corresponding data from the Horizon API. +/// +/// # Example +/// ``` +/// use stellar_rs::transactions::all_transactions_request::AllTransactionsRequest; +/// use stellar_rs::models::{Order}; +/// use stellar_rust_sdk_derive::Pagination; +/// use stellar_rs::Paginatable; +/// +/// let request = AllTransactionsRequest::new() +/// .set_include_failed(true).unwrap() // Optional flag to include failed transactions +/// .set_cursor(123).unwrap() // Optional cursor for pagination +/// .set_limit(100).unwrap() // Optional limit for response records +/// .set_order(Order::Desc); // Optional order of records +/// +/// // Use with HorizonClient::get_all_transactions +/// ``` +/// #[derive(Default, Pagination)] pub struct AllTransactionsRequest { // Indicates whether or not to include failed operations in the response. @@ -29,7 +57,6 @@ impl Request for AllTransactionsRequest { .build_query_parameters() } - // TODO: Documentation fn build_url(&self, base_url: &str) -> String { format!( "{}/{}{}", @@ -46,7 +73,10 @@ impl AllTransactionsRequest { AllTransactionsRequest::default() } - // TODO: Documentation + /// Specifies whether to include failed operations in the response. + /// + /// # Arguments + /// * `include_failed` (bool) - when set to `true`, failed operations will be included. pub fn set_include_failed(self, include_failed: bool) -> Result { Ok(AllTransactionsRequest { include_failed: Some(include_failed), diff --git a/stellar_rust_sdk/src/transactions/mod.rs b/stellar_rust_sdk/src/transactions/mod.rs index 0e27940..ac52000 100644 --- a/stellar_rust_sdk/src/transactions/mod.rs +++ b/stellar_rust_sdk/src/transactions/mod.rs @@ -8,7 +8,14 @@ /// pub mod single_transaction_request; -/// TODO: Documentation +/// Provides the `AllTransactionsRequest`. +/// +/// # Usage +/// This module provides the `AllTransactionsRequest` struct, specifically designed for +/// constructing requests to query information about all transactions from the Horizon +/// server. It is tailored for use with the [`HorizonClient::get_all_transactions`](crate::horizon_client::HorizonClient::get_all_transactions) +/// method. +/// pub mod all_transactions_request; /// Provides the responses. @@ -26,7 +33,7 @@ pub mod response; /// /// # Usage /// This variable is intended to be used internally by the request-building logic -/// to ensure consistent and accurate path construction for offer-related API calls. +/// to ensure consistent and accurate path construction for transaction-related API calls. static TRANSACTIONS_PATH: &str = "transactions"; /// The `prelude` module of the `transactions` module. @@ -67,7 +74,7 @@ pub mod prelude { #[cfg(test)] pub mod test { use super::prelude::*; - use crate::{horizon_client::HorizonClient, models::Request}; + use crate::horizon_client::HorizonClient; #[tokio::test] async fn test_get_single_transaction() { @@ -179,7 +186,8 @@ pub mod test { .to_string()) .unwrap(); - let all_transactions_request = AllTransactionsRequest::new().set_include_failed(true).unwrap(); + let all_transactions_request = AllTransactionsRequest::new() + .set_include_failed(true).unwrap(); let all_transactions_response = horizon_client .get_all_transactions(&all_transactions_request) diff --git a/stellar_rust_sdk/src/transactions/response.rs b/stellar_rust_sdk/src/transactions/response.rs index aa81a09..324e1a1 100644 --- a/stellar_rust_sdk/src/transactions/response.rs +++ b/stellar_rust_sdk/src/transactions/response.rs @@ -72,7 +72,11 @@ pub struct LedgerBounds { max_ledger: Option, } -// TODO: Documentation +/// Represents the response for the 'all transactions' query in the Horizon API. +/// +/// This struct defines the overall structure of the response for an 'all transactions' query. +/// It includes navigational links and embedded results. +/// #[derive(Debug, Clone, Serialize, Deserialize, Getters)] #[serde(rename_all = "camelCase")] pub struct AllTransactionsResponse {