From 609e5632e888afad3c67b1a4179d467b86745fc3 Mon Sep 17 00:00:00 2001
From: om-ghante <mr.omghante1@gmail.com>
Date: Sun, 26 Apr 2026 20:03:29 +0530
Subject: [PATCH] docs: add class-level Javadoc to BaseClient,
 CustomCheckoutClient, and SubscriptionClient

- BaseClient: document its role as shared base for OAuth, HTTP, and telemetry
- CustomCheckoutClient: document PCI routing and device OS handling
- SubscriptionClient: document autopay flows (setup, notify, redeem, cancel)
- Add @see cross-references between all client classes

Fixes #45
---
 .../com/phonepe/sdk/pg/common/BaseClient.java     | 11 +++++++++++
 .../sdk/pg/payments/v2/CustomCheckoutClient.java  | 15 +++++++++++++++
 .../pg/subscription/v2/SubscriptionClient.java    | 14 ++++++++++++++
 3 files changed, 40 insertions(+)

diff --git a/src/main/java/com/phonepe/sdk/pg/common/BaseClient.java b/src/main/java/com/phonepe/sdk/pg/common/BaseClient.java
index 3e7cb7d..f12e299 100644
--- a/src/main/java/com/phonepe/sdk/pg/common/BaseClient.java
+++ b/src/main/java/com/phonepe/sdk/pg/common/BaseClient.java
@@ -37,6 +37,17 @@
 import okhttp3.OkHttpClient;
 
 @Getter
+/**
+ * Abstract base class for all PhonePe Payment Gateway SDK clients.
+ *
+ * <p>Provides shared functionality including OAuth2 token management,
+ * authenticated HTTP request execution with automatic token refresh,
+ * and SDK event telemetry publishing.</p>
+ *
+ * @see com.phonepe.sdk.pg.payments.v2.StandardCheckoutClient
+ * @see com.phonepe.sdk.pg.payments.v2.CustomCheckoutClient
+ * @see com.phonepe.sdk.pg.subscription.v2.SubscriptionClient
+ */
 public abstract class BaseClient {
 
 	private final ObjectMapper objectMapper;
diff --git a/src/main/java/com/phonepe/sdk/pg/payments/v2/CustomCheckoutClient.java b/src/main/java/com/phonepe/sdk/pg/payments/v2/CustomCheckoutClient.java
index ef5bd16..0bab279 100644
--- a/src/main/java/com/phonepe/sdk/pg/payments/v2/CustomCheckoutClient.java
+++ b/src/main/java/com/phonepe/sdk/pg/payments/v2/CustomCheckoutClient.java
@@ -50,6 +50,21 @@
 import java.util.List;
 import lombok.SneakyThrows;
 
+/**
+ * The CustomCheckout client class provides methods for interacting with
+ * PhonePe's Custom Checkout Payment Gateway APIs.
+ *
+ * <p>Use this client when you need full control over the payment experience,
+ * including direct card/token instrument handling with PCI-compliant routing
+ * and device OS header injection.</p>
+ *
+ * <p>For a simpler integration where PhonePe handles the checkout UI,
+ * use {@link StandardCheckoutClient} instead.</p>
+ *
+ * @see StandardCheckoutClient
+ * @see com.phonepe.sdk.pg.subscription.v2.SubscriptionClient
+ * @see com.phonepe.sdk.pg.common.BaseClient
+ */
 public class CustomCheckoutClient extends BaseClient {
 
 	private List<HttpHeaderPair> headers;
diff --git a/src/main/java/com/phonepe/sdk/pg/subscription/v2/SubscriptionClient.java b/src/main/java/com/phonepe/sdk/pg/subscription/v2/SubscriptionClient.java
index f720677..6772476 100644
--- a/src/main/java/com/phonepe/sdk/pg/subscription/v2/SubscriptionClient.java
+++ b/src/main/java/com/phonepe/sdk/pg/subscription/v2/SubscriptionClient.java
@@ -43,6 +43,20 @@
 import java.util.List;
 import lombok.SneakyThrows;
 
+/**
+ * The Subscription client class provides methods for interacting with
+ * PhonePe's Subscription (Autopay) Payment Gateway APIs.
+ *
+ * <p>Use this client to manage recurring payment mandates, including
+ * setup, notification, redemption, cancellation, and status queries.</p>
+ *
+ * <p>For one-time payments, use {@link com.phonepe.sdk.pg.payments.v2.StandardCheckoutClient}
+ * or {@link com.phonepe.sdk.pg.payments.v2.CustomCheckoutClient} instead.</p>
+ *
+ * @see com.phonepe.sdk.pg.payments.v2.StandardCheckoutClient
+ * @see com.phonepe.sdk.pg.payments.v2.CustomCheckoutClient
+ * @see com.phonepe.sdk.pg.common.BaseClient
+ */
 public class SubscriptionClient extends BaseClient {
 
 	private List<HttpHeaderPair> headers;