Document entire crate (#21)

Author: ejorritsma

src/accounts/accounts_request.rs

@@ -3,87 +3,159 @@ use serde::{Deserialize, Serialize};
 
 use crate::models::Response;
 
-/// Struct defining the self link in the list all accounts response.
+/// Represents the self-link in the list of all accounts response.
+///
+/// This struct defines the structure of the self-link (`href`) found in the accounts response
+/// from the Horizon API. It contains the URL to the current resource or query.
+///
 #[derive(Debug, Deserialize, Serialize, Clone, Getters)]
 pub struct AccountsResponseSelfLink {
+    /// A `String` representing the hyperlink reference to the current resource or query.
     href: String,
 }
 
-/// Struct defining the links in the list all accounts response.
+/// Represents the various links in the list of all accounts response.
+///
+/// This struct encapsulates the different types of navigational links (self, next, previous) 
+/// in the accounts response. Each link is an instance of [`AccountsResponseSelfLink`].
+///
 #[derive(Debug, Deserialize, Serialize, Clone, Getters)]
 pub struct AccountsResponseLinks {    
     #[serde(rename = "self")]
+    /// The link to the current page of account records.
     self_link: AccountsResponseSelfLink,
+    /// An optional link to the next page of account records.
     next: Option<AccountsResponseSelfLink>,
+    /// An optional link to the previous page of account records.
     prev: Option<AccountsResponseSelfLink>,
 }
 
-/// Struct defining a single balance in the list all accounts response.
+/// Represents a single balance within an account in the list of all accounts response.
+///
+/// This struct details the balance information for an account, including the type of asset
+/// and the associated liabilities.
+///
 #[derive(Debug, Deserialize, Serialize, Clone, Getters)]
 pub struct Balances {
+    /// The total balance of the asset.
     balance: String,
+    /// Buying liabilities associated with the asset.
     buying_liabilities: String,
+    /// Selling liabilities associated with the asset.
     selling_liabilities: String,
+    /// The type of asset (e.g., native, credit_alphanum4, credit_alphanum12).
     asset_type: String,
 }
 
-/// Struct defining the thresholds in the list all accounts response.
+/// Represents the thresholds associated with an account in the list of all accounts response.
+///
+/// This struct encapsulates the various threshold values for different operations in an account.
+///
 #[derive(Debug, Deserialize, Serialize, Clone, Getters)]
 pub struct AccountsResponseThresholds {
+    /// The threshold for low-level operations.
     low_threshold: i32,
+    /// The threshold for medium-level operations.
     med_threshold: i32,
+    /// The threshold for high-level operations.
     high_threshold: i32,
 }
 
-/// Struct defining the flags in the list all accounts response.
+/// Represents the flags set on an account in the list of all accounts response.
+///
+/// This struct defines the various boolean flags that can be set on an account, 
+/// indicating specific permissions or settings.
+///
 #[derive(Debug, Deserialize, Serialize, Clone, Getters)]
 pub struct AccountsResponseFlags {
+    /// Indicates if authorization is required for transactions.
     auth_required: bool,
+    /// Indicates if authorization can be revoked.
     auth_revocable: bool,
+    /// Indicates if the account's authorization settings cannot be changed.
     auth_immutable: bool,
+    /// Indicates if the clawback feature is enabled.
     auth_clawback_enabled: bool,
 }
 
-/// Struct defining a single signer in the list all accounts response.
+/// Represents a signer associated with an account in the list of all accounts response.
+///
+/// This struct details the information about a signer for an account, including their 
+/// key, type, and weight in authorization decisions.
+///
 #[derive(Debug, Deserialize, Serialize, Clone, Getters)]
 pub struct Signers {
+    /// The weight of the signer's vote in authorization decisions.
     weight: i32,
+    /// The key associated with the signer.
     key: String,
+    /// The type of the signer (e.g., 'ed25519_public_key').
     #[serde(rename = "type")]
     signer_type: String,
 }
 
-/// Struct defining a record of a single account in the list all accounts response.
+/// Represents a single account record in the list of all accounts response.
+///
+/// This struct encapsulates detailed information about an individual account as returned
+/// in the Horizon API response. It includes various fields like account identifiers, 
+/// thresholds, flags, balances, and more.
+///
 #[derive(Debug, Deserialize, Serialize, Clone, Getters)]
 pub struct Record {
+    /// Links associated with this account record.
     #[serde(rename = "_links")]
     links: AccountsResponseLinks,
+    /// The unique identifier of the account.
     id: String,
+    /// The public key of the account.
     account_id: String,
+    /// The sequence number of the account.
     sequence: String,
+    /// The number of subentries in the account.
     subentry_count: i32,
     last_modified_ledger: u64,
     last_modified_time: String,
+    /// The thresholds for different operations in the account.
     thresholds: AccountsResponseThresholds,
+    /// The flags set on the account.
     flags: AccountsResponseFlags,
+    /// A list of balances for different assets held by the account.
     balances: Vec<Balances>,
+    /// A list of signers associated with the account.
     signers: Vec<Signers>,
+    /// Additional data associated with the account (in JSON format).
     data: serde_json::Value,
+    /// The number of entries the account is sponsoring.
     num_sponsoring: i32,
+    /// The number of entries the account is sponsored for.
     num_sponsored: i32,
+    /// A token used for paging through results.
     paging_token: String,
 }
 
-/// Struct defining the embedded object in the list all accounts response.
+/// Represents the embedded part of the list all accounts response.
+///
+/// This struct is used to hold the actual array of account records ([`Record`]) as part of 
+/// the Horizon API response. It serves as a container for the data portion of the response.
+///
 #[derive(Debug, Deserialize, Serialize, Clone, Getters)]
 pub struct Embedded {
+    /// * `records`: A vector of [`Record`] structs, each representing an individual account.
     records: Vec<Record>,
 }
 
-/// Struct defining the list all accounts response.
+
+/// Represents the entire response for the list all accounts query.
+///
+/// This struct defines the overall structure of the response returned from the Horizon API 
+/// when querying for multiple accounts. It includes navigational links and the embedded data 
+/// containing account records.
+///
 #[derive(Debug, Deserialize, Serialize, Clone, Getters)]
 pub struct AccountsResponse {
+    /// Navigational links related to the response.
     _links: AccountsResponseLinks,
+    /// The embedded object containing the actual account records.
     _embedded: Embedded,
 }
 

src/accounts/accounts_response.rs

@@ -1,10 +1,89 @@
+/// Provides the `AccountsRequest`.
+///
+/// This module provides the `AccountsRequest` struct, which is specifically designed
+/// for constructing requests to query for multiple accounts from the Horizon server. It is
+/// is meant to be used with the [`HorizonClient::get_accounts_list`](crate::horizon_client::HorizonClient::get_account_list)
+/// method.
+///
 pub mod accounts_request;
+
+
+/// Provides the `AccountsResponse`.
+///
+/// This module provides a set of structures that represent the response received from the Horizon
+/// API when querying for accounts. These structures are designed to translate the JSON response
+/// from the Horizon server into proper Rust objects, facilitating the processing and utilization
+/// of account data within the client application.
+/// For a more elaborate overview of the returned values, please refer to the documentation of the 
+/// <a href="https://developers.stellar.org/api/horizon/resources/list-all-accounts">List All Accounts endpoint</a>.
+///
+/// These structures are mainly used internally by the `HorizonClient` when processing responses from 
+/// account-related API calls. The [`AccountsResponse`](crate::accounts::accounts_response::AccountsResponse) struct is of special importance here, 
+/// as it is returned by the [`HorizonClient::get_accounts_list`](crate::horizon_client::HorizonClient::get_account_list) method, 
+/// providing a user-friendly way to access account data.
+///
 pub mod accounts_response;
+
+
+/// Provides the `SingleAccountRequest`.
+///
+/// This module provides the `SingleAccountRequest` struct, specifically designed for 
+/// constructing requests to query information about a single account from the Horizon 
+/// server. It is tailored for use with the [`HorizonClient::get_single_account`](crate::horizon_client::HorizonClient::get_single_account) 
+/// method.
+///
 pub mod single_account_request;
+
+
+/// Provides the `SingleAccountResponse`.
+///
+/// This module defines structures representing the response from the Horizon API when querying 
+/// for a single account. The structures are designed to deserialize the JSON response into Rust 
+/// objects, enabling straightforward access to various details of a single Stellar account.
+/// 
+/// These structures are equipped with serialization capabilities to handle the JSON data from the 
+/// Horizon server and with getter methods for easy field access.
+///
 pub mod single_account_response;
 
+/// The base path for account-related endpoints in the Horizon API.
+/// 
+/// # Usage
+/// This variable is intended to be used internally by the request-building logic
+/// to ensure consistent and accurate path construction for account-related API calls.
+///
 static ACCOUNTS_PATH: &str = "accounts";
 
+/// The `prelude` module of the `accounts` module.
+///
+/// This module serves as a convenience for users of the Horizon Rust SDK, allowing for easy and 
+/// ergonomic import of the most commonly used items across various modules. It re-exports 
+/// key structs and traits from the sibling modules, simplifying access to these components 
+/// when using the library.
+///
+/// By importing the contents of `prelude`, users can conveniently access the primary 
+/// functionalities of the accounts-related modules without needing to import each item 
+/// individually.
+///
+/// # Contents
+///
+/// The `prelude` includes the following re-exports:
+///
+/// * From `accounts_request`: All items (e.g., `AccountsRequest`).
+/// * From `accounts_response`: All items (e.g., `AccountsResponse`, `Record`, etc.).
+/// * From `single_account_request`: All items (e.g., `SingleAccountRequest`).
+/// * From `single_account_response`: All items (e.g., `SingleAccountResponse`, `Balance`, etc.).
+///
+/// # Example
+/// ```
+/// # use crate::stellar_rust_sdk::models::*;
+/// // Import the contents of the account prelude
+/// use stellar_rust_sdk::accounts::prelude::*;
+///
+/// // Now you can directly use AccountsRequest, SingleAccountResponse, etc.
+/// let account_request = AccountsRequest::new();
+/// ```
+///
 pub mod prelude {
     pub use super::accounts_request::*;
     pub use super::accounts_response::*;

src/accounts/mod.rs

@@ -1,29 +1,55 @@
 use crate::models::{is_public_key, Request};
 
+/// Represents a query parameter for the account's public key
 #[derive(Default, Clone)]
 pub struct AccountId(String);
+/// Represents the absence of a query parameter for the account's public key
 #[derive(Default, Clone)]
 pub struct NoAccountId;
 
-/// SingleAccountRequest is the request for the /accounts endpoint to get a single account.
-/// [More Details](https://developers.stellar.org/api/horizon/resources/retrieve-an-account "Accounts")
+/// Represents a request to fetch details of a single account from the Horizon API.
+///
+/// `SingleAccountRequest` is a struct tailored to querying details of a specific account
+/// on the Horizon API. This struct is designed to be used in conjunction with the
+/// [`HorizonClient::get_single_account`](crate::horizon_client::HorizonClient::get_single_account) method.
+///
+/// The struct matches the parameters necessary to construct a request for the
+/// <a href="https://developers.stellar.org/api/horizon/resources/retrieve-an-account">Retrieve An Account endpoint</a>
+/// of the Horizon API.
+///
+/// # Fields
+/// Required:
+/// * `account_id` - The account's public key.
+///
+/// ## Usage
+/// Instances of `SingleAccountRequest` are created and configured using setter methods for each
+/// parameter.
+/// ```
+/// # use stellar_rust_sdk::accounts::prelude::SingleAccountRequest;
+/// # use stellar_rust_sdk::models::Request;
+/// let request = SingleAccountRequest::new()
+///     .set_account_id("GDQJUTQYK2MQX2VGDR2FYWLIYAQIEGXTQVTFEMGH2BEWFG4BRUY4CKI7".to_string())
+///     .unwrap();
+/// // Use with HorizonClient::get_single_account
+/// ```
+///
 #[derive(Default)]
 pub struct SingleAccountRequest<I> {
-    /// Account ID of the sponsor. Every account in the response will either be sponsored by the given account ID or have a subentry (trustline, offer, or data entry) which is sponsored by the given account ID.
+    /// The account's public key.
     account_id: I,
 }
 
 impl SingleAccountRequest<NoAccountId> {
+    /// Creates a new `SingleAccountRequest` with default parameters.
     pub fn new() -> Self {
         SingleAccountRequest::default()
     }
 
-    /// Sets the account ID of the account to get.
+    /// Sets the account ID for the request.
+    ///
     /// # Arguments
-    /// * `account_id` - The account ID of the account to get.
-    /// # Returns
-    /// The request object
-    /// [SingleAccountRequest](struct.SingleAccountRequest.html)
+    /// * `account_id` - A `String` specifying the account's public key.
+    ///
     pub fn set_account_id(
         self,
         account_id: String,