From 3124737a9aa223ef84fb401af9db9b2ed8a64035 Mon Sep 17 00:00:00 2001
From: Kevin Pease <kevin@baseflow.com>
Date: Tue, 20 Aug 2024 14:06:00 +0200
Subject: [PATCH] Add documentation

---
 .../src/effects/all_effects_request.rs        |  1 +
 .../src/ledgers/ledgers_request.rs            |  1 +
 .../src/payments/all_payments_request.rs      |  1 +
 stellar_rust_sdk_derive/src/lib.rs            | 31 ++++++++++++++++++-
 4 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/stellar_rust_sdk/src/effects/all_effects_request.rs b/stellar_rust_sdk/src/effects/all_effects_request.rs
index cd6a8cb..8500826 100644
--- a/stellar_rust_sdk/src/effects/all_effects_request.rs
+++ b/stellar_rust_sdk/src/effects/all_effects_request.rs
@@ -28,6 +28,7 @@ use stellar_rust_sdk_derive::pagination;
 #[pagination]
 #[derive(Default)]
 pub struct AllEffectsRequest {
+    // All fields are injected by the `pagination` macro.
 }
 
 impl AllEffectsRequest {
diff --git a/stellar_rust_sdk/src/ledgers/ledgers_request.rs b/stellar_rust_sdk/src/ledgers/ledgers_request.rs
index 629af0e..1fb3890 100644
--- a/stellar_rust_sdk/src/ledgers/ledgers_request.rs
+++ b/stellar_rust_sdk/src/ledgers/ledgers_request.rs
@@ -28,6 +28,7 @@ use stellar_rust_sdk_derive::pagination;
 #[pagination]
 #[derive(Default)]
 pub struct LedgersRequest {
+    // All fields are injected by the `pagination` macro.
 }
 
 impl LedgersRequest {
diff --git a/stellar_rust_sdk/src/payments/all_payments_request.rs b/stellar_rust_sdk/src/payments/all_payments_request.rs
index efafe11..fd33e55 100644
--- a/stellar_rust_sdk/src/payments/all_payments_request.rs
+++ b/stellar_rust_sdk/src/payments/all_payments_request.rs
@@ -5,6 +5,7 @@ use stellar_rust_sdk_derive::pagination;
 #[pagination]
 #[derive(Default)]
 pub struct AllPaymentsRequest {
+    // All fields are injected by the `pagination` macro.
 }
 
 impl AllPaymentsRequest {
diff --git a/stellar_rust_sdk_derive/src/lib.rs b/stellar_rust_sdk_derive/src/lib.rs
index fa87ed3..f0d837d 100644
--- a/stellar_rust_sdk_derive/src/lib.rs
+++ b/stellar_rust_sdk_derive/src/lib.rs
@@ -3,11 +3,35 @@ use proc_macro::TokenStream;
 use quote::quote;
 use syn::{parse_macro_input, ItemStruct, Fields, Field};
 
+/// The procedural attribute macro to add pagination functionality to request structs.
+///
+/// This macro automatically injects pagination-related fields and methods into a struct
+/// to facilitate paginated API requests. Specifically, it adds three optional fields
+/// and three methods:
+///
+/// - `cursor`: An `Option<u32>` field that represents the pagination cursor. The cursor
+///   is used to track the current position in a paginated dataset. The `set_cursor` method
+///   allows setting this field, with a validation that ensures the cursor is greater than
+///   or equal to 1.
+///
+/// - `limit`: An `Option<u8>` field that specifies the maximum number of items to retrieve
+///   in a single page. The `set_limit` method allows setting this field, ensuring that the
+///   limit is within a valid range (between 1 and 200).
+///
+/// - `order`: An `Option<Order>` field that defines the sort order of the paginated results.
+///   The `set_order` method allows setting this field without additional validation, as the
+///   sort order is context-dependent.
+///
+/// # Usage
+///
+/// Apply the `#[pagination]` attribute to a struct to automatically add pagination
+/// functionality.
+///
 #[proc_macro_attribute]
 pub fn pagination(_attr: TokenStream, input: TokenStream) -> TokenStream {
     let mut input = parse_macro_input!(input as ItemStruct);
 
-    // create req'd fields
+    // Create required fields to be added to the struct.
     let cursor_field: Field = syn::parse_quote! {
         pub cursor: Option<u32>
     };
@@ -18,6 +42,7 @@ pub fn pagination(_attr: TokenStream, input: TokenStream) -> TokenStream {
         pub order: Option<Order>
     };
 
+    // Add the fields to the struct.
     if let Fields::Named(ref mut fields) = input.fields {
         fields.named.push(cursor_field);
         fields.named.push(limit_field);
@@ -25,7 +50,11 @@ pub fn pagination(_attr: TokenStream, input: TokenStream) -> TokenStream {
     }
 
     let struct_name = &input.ident;
+
+    // Split the generics into implementation, type, and where clause parts, so that the macro supports generic structs.
     let (impl_generics, type_generics, where_clause) = input.generics.split_for_impl();
+
+    // Add methods to the struct.
     let expanded = quote! {
         #input
         impl #impl_generics #struct_name #type_generics #where_clause {