merchant

commit 089f3b56928435993d6f083d51732965ff7ba149
parent 2861254de6321015394591e0da1a61086134e86e
Author: bohdan-potuzhnyi <bohdan.potuzhnyi@gmail.com>
Date:   Wed, 16 Jul 2025 12:20:32 +0200

adding some more comments to the merchant_pay_service.c

Diffstat:
M
src/lib/taler_merchant_pay_service.c
 | 
39
+++++++++++++++++++++++++++++++++++++++

1 file changed, 39 insertions(+), 0 deletions(-)
diff --git a/src/lib/taler_merchant_pay_service.c b/src/lib/taler_merchant_pay_service.c
@@ -536,6 +536,12 @@ handle_finished (void *cls,
 }
 
 
+/**
+ * @brief Create and initialize a new payment handle
+ *
+ * Allocates a TALER_MERCHANT_OrderPayHandle, sets up its context and
+ * prepares an empty JSON body for the /orders/$ID/pay request.
+ */
 struct TALER_MERCHANT_OrderPayHandle *
 TALER_MERCHANT_order_pay_create (struct GNUNET_CURL_Context *ctx,
                                  TALER_MERCHANT_OrderPayCallback cb,
@@ -553,6 +559,12 @@ TALER_MERCHANT_order_pay_create (struct GNUNET_CURL_Context *ctx,
 }
 
 
+/**
+ * @brief Cancel and free a payment handle
+ *
+ * Aborts any in-flight CURL job, releases all JSON objects and internal
+ * buffers, and frees the handle structure itself.
+ */
 void
 TALER_MERCHANT_order_pay_cancel1 (struct TALER_MERCHANT_OrderPayHandle *ph)
 {
@@ -585,6 +597,18 @@ TALER_MERCHANT_order_pay_cancel1 (struct TALER_MERCHANT_OrderPayHandle *ph)
 }
 
 
+/**
+ * @brief Store a JSON snippet under a payment option key
+ *
+ * Ensures that an option of type @a ot has not already been set,
+ * then merges @a snippet into the handle's JSON @c body. Marks the
+ * field_seen flag and frees @a snippet.
+ *
+ * @param ph   payment handle receiving the snippet
+ * @param ot   option type under which to store @a snippet
+ * @param snippet JSON object representing the option payload
+ * @return #TALER_MERCHANT_OPOEC_OK if stored; appropriate error code otherwise
+ */
 static enum TALER_MERCHANT_OrderPayOptionErrorCode
 store_json_option (struct TALER_MERCHANT_OrderPayHandle *ph,
                    enum TALER_MERCHANT_OrderPayOptionType ot,
@@ -602,6 +626,13 @@ store_json_option (struct TALER_MERCHANT_OrderPayHandle *ph,
 }
 
 
+/**
+ * @brief Apply user-supplied options to a payment handle
+ *
+ * Iterates through a NULL-terminated array of #TALER_MERCHANT_OrderPayOption
+ * entries, validates and stores each into @a ph. Handles JSON packing and
+ * internal state updates for coins, tokens, deadlines, Donau data, etc.
+ */
 enum TALER_MERCHANT_OrderPayOptionErrorCode
 TALER_MERCHANT_order_pay_set_options (struct TALER_MERCHANT_OrderPayHandle *ph,
                                       const struct TALER_MERCHANT_OrderPayOption
@@ -780,6 +811,14 @@ TALER_MERCHANT_order_pay_set_options (struct TALER_MERCHANT_OrderPayHandle *ph,
 }
 
 
+/**
+ * @brief Dispatch the /orders/$ID/pay request
+ *
+ * Validates that all mandatory parameters (merchant_url, order_id, coins)
+ * have been set, builds the final JSON payload, constructs the URL,
+ * and issues an asynchronous HTTP POST. The payment handle's callback
+ * will receive completion notifications.
+ */
 enum TALER_MERCHANT_OrderPayOptionErrorCode
 TALER_MERCHANT_order_pay_start (struct TALER_MERCHANT_OrderPayHandle *ph)
 {