commit 4ae9fb6642cbd365bcff30761b935fb56bbbe969 parent 57c9bcf54e4dc98b6a16344d28c306ad9e5ef8b8 Author: bohdan-potuzhnyi <bohdan.potuzhnyi@gmail.com> Date: Wed, 16 Jul 2025 10:26:53 +0200 some doxygen fixes Diffstat:
20 files changed, 56 insertions(+), 45 deletions(-)
diff --git a/src/backend/taler-merchant-depositcheck.c b/src/backend/taler-merchant-depositcheck.c @@ -595,7 +595,7 @@ deposit_get_cb ( * @param cls NULL * @param deposit_serial identifies the deposit operation * @param wire_deadline when is the wire due - * @param retry_backoff current value for the retry backoff + * @param retry_time current value for the retry backoff * @param h_contract_terms hash of the contract terms * @param merchant_priv private key of the merchant * @param instance_id row ID of the instance diff --git a/src/backend/taler-merchant-donaukeyupdate.c b/src/backend/taler-merchant-donaukeyupdate.c @@ -172,7 +172,7 @@ static bool at_limit; /** * Function that initiates a /keys download for a Donau instance. * - * @param cls a `struct Donau *` + * @param cls closure with a `struct Donau *` */ static void download_keys (void *cls); diff --git a/src/backend/taler-merchant-httpd.c b/src/backend/taler-merchant-httpd.c @@ -531,7 +531,7 @@ TMH_check_auth (const char *password, * * @param userpass base64 encoded "$USERNAME:$PASSWORD" value * from HTTP Basic "Authentication" header - * @param instances the access controlled instance + * @param instance the access controlled instance */ static enum GNUNET_GenericReturnValue check_auth_instance (const char *userpass, diff --git a/src/backend/taler-merchant-httpd_post-orders-ID-pay.c b/src/backend/taler-merchant-httpd_post-orders-ID-pay.c @@ -2961,7 +2961,7 @@ test_tfk_mandatory (enum TALER_MERCHANTDB_TokenFamilyKind tfk) /** * Sign the tokens provided by the wallet for a particular @a key. * - * @param[in,out] payment we are processing + * @param[in,out] pc reference for payment we are processing * @param key token family data * @param priv private key to use to sign with * @param mandatory true if the token must exist, if false diff --git a/src/backend/taler-merchant-httpd_private-get-donau-instances.c b/src/backend/taler-merchant-httpd_private-get-donau-instances.c @@ -14,7 +14,7 @@ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> */ /** - * @file taler-merchant-httpd_get-donau-instances.c + * @file taler-merchant-httpd_private-get-donau-instances.c * @brief implementation of GET /donau * @author Bohdan Potuzhnyi * @author Vlada Svirsh @@ -31,7 +31,7 @@ /** * Add details about a Donau instance to the JSON array. * - * @param json_instances JSON array to which Donau instance information is added + * @param cls json array to which the Donau instance details will be added * @param donau_url the URL of the Donau instance * @param charity_name the name of the charity * @param charity_pub_key the public key of the charity diff --git a/src/backend/taler-merchant-httpd_private-get-donau-instances.h b/src/backend/taler-merchant-httpd_private-get-donau-instances.h @@ -14,7 +14,7 @@ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> */ /** - * @file taler-merchant-httpd_get-donau-instances.h + * @file taler-merchant-httpd_private-get-donau-instances.h * @brief implementation of GET /donau * @author Bohdan Potuzhnyi * @author Vlada Svirsh diff --git a/src/backend/taler-merchant-httpd_private-get-incoming.c b/src/backend/taler-merchant-httpd_private-get-incoming.c @@ -33,7 +33,7 @@ * @param wtid wire transfer identifier * @param payto_uri target account that received the wire transfer * @param exchange_url base URL of the exchange that made the wire transfer - * @param transfer_serial_id serial number identifying the transfer in the backend + * @param expected_transfer_serial_id serial number identifying the transfer in the backend * @param execution_time when did the exchange make the transfer, #GNUNET_TIME_UNIT_FOREVER_ABS * if it did not yet happen * @param confirmed true if the merchant acknowledged the wire transfer reception diff --git a/src/backend/taler-merchant-httpd_private-get-instances-ID-tokens.c b/src/backend/taler-merchant-httpd_private-get-instances-ID-tokens.c @@ -26,8 +26,11 @@ * Add token details to our JSON array. * * @param cls a `json_t *` JSON array to build - * @param product_serial serial (row) number of the product in the database - * @param product_id ID of the product + * @param creation_time when the token was created + * @param expiration_time when the token will expire + * @param scope internal scope identifier for the token (mapped to string) + * @param description human-readable purpose or context of the token + * @param serial serial (row) number of the product in the database */ static void add_token (void *cls, diff --git a/src/backend/taler-merchant-httpd_private-get-statistics-amount-SLUG.c b/src/backend/taler-merchant-httpd_private-get-statistics-amount-SLUG.c @@ -32,8 +32,8 @@ * @param bucket_start start time of the bucket * @param bucket_end end time of the bucket * @param bucket_range range of the bucket - * @param cumulative_amounts_len the length of @a cumulative_amounts - * @param cumulative_amounts the cumulative amounts array + * @param amounts_len the length of @a cumulative_amounts + * @param amounts the cumulative amounts array */ static void amount_by_bucket (void *cls, @@ -97,9 +97,9 @@ amount_by_bucket (void *cls, * * @param cls a `json_t *` JSON array to build * @param description description of the statistic - * @param interval_start start time of the bucket - * @param cumulative_amounts_len the length of @a cumulative_amounts - * @param cumulative_amounts the cumulative amounts array + * @param bucket_start start time of the bucket + * @param amounts_len the length of @a cumulative_amounts + * @param amounts the cumulative amounts array */ static void amount_by_interval (void *cls, diff --git a/src/backend/taler-merchant-httpd_private-get-statistics-counter-SLUG.c b/src/backend/taler-merchant-httpd_private-get-statistics-counter-SLUG.c @@ -33,7 +33,7 @@ * @param bucket_start start time of the bucket * @param bucket_end end time of the bucket * @param bucket_range range of the bucket - * @param cumulative_counter counter value + * @param cumulative_number counter value */ static void counter_by_bucket (void *cls, @@ -86,8 +86,8 @@ counter_by_bucket (void *cls, * * @param cls a `json_t *` JSON array to build * @param description description of the statistic - * @param interval_start start time of the interval - * @param cumulative_counter counter value + * @param bucket_start start time of the interval + * @param cumulative_number counter value */ static void counter_by_interval (void *cls, diff --git a/src/backend/taler-merchant-httpd_private-get-transfers.c b/src/backend/taler-merchant-httpd_private-get-transfers.c @@ -30,14 +30,14 @@ * Generate a response (array entry) based on the given arguments. * * @param cls closure with a `json_t *` array to build up the response - * @param expected_credit_amount amount expected to be wired to the merchant (minus fees), NULL if unknown + * @param credit_amount amount expected to be wired to the merchant (minus fees), NULL if unknown * @param wtid wire transfer identifier * @param payto_uri target account that received the wire transfer * @param exchange_url base URL of the exchange that made the wire transfer * @param transfer_serial_id serial number identifying the transfer in the backend * @param execution_time when did the exchange make the transfer, #GNUNET_TIME_UNIT_FOREVER_ABS * if it did not yet happen - * @param confirmed true if the merchant acknowledged the wire transfer reception + * @param expected true if the merchant acknowledged the wire transfer reception */ static void transfer_cb (void *cls, diff --git a/src/backend/taler-merchant-httpd_private-post-donau-instance.c b/src/backend/taler-merchant-httpd_private-post-donau-instance.c @@ -14,7 +14,7 @@ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> */ /** - * @file taler-merchant-httpd_post-donau-instance.c + * @file taler-merchant-httpd_private-post-donau-instance.c * @brief implementation of POST /donau * @author Bohdan Potuzhnyi * @author Vlada Svirsh diff --git a/src/backend/taler-merchant-httpd_private-post-donau-instance.h b/src/backend/taler-merchant-httpd_private-post-donau-instance.h @@ -14,7 +14,7 @@ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> */ /** - * @file taler-merchant-httpd_post-donau-instance.h + * @file taler-merchant-httpd_private-post-donau-instance.h * @brief implementation of POST /donau * @author Bohdan Potuzhnyi * @author Vlada Svirsh diff --git a/src/backend/taler-merchant-httpd_private-post-orders.c b/src/backend/taler-merchant-httpd_private-post-orders.c @@ -1895,7 +1895,7 @@ add_output_token_family (struct OrderContext *oc, * Build JSON array that represents all of the token families * in the contract. * - * @param[in] v1-style order + * @param[in] oc v1-style order context * @return JSON array with token families for the contract */ static json_t * @@ -1927,7 +1927,7 @@ output_token_families (struct OrderContext *oc) * Build JSON array that represents all of the contract choices * in the contract. * - * @param[in] v1-style order + * @param[in] oc v1-style order context * @return JSON array with token families for the contract */ static json_t * @@ -2237,7 +2237,7 @@ resume_with_keys (struct OrderContext *oc) * @a stefan_fee. Note that @a stefan_fee is updated to the maximum * of the input and the computed fee. * - * @param[in,out] oc order context + * @param[in,out] keys exchange keys * @param brutto some brutto amount the client is to pay * @param[in,out] stefan_fee set to STEFAN fee to be paid by the merchant */ @@ -2629,7 +2629,7 @@ wakeup_timeout (void *cls) * * @param oc order context to check * @param brutto amount to check - * @param true if the amount is OK, false if it is too high + * @return true if the amount is OK, false if it is too high */ static bool check_exchange_limits (const struct OrderContext *oc, diff --git a/src/backenddb/pg_insert_donau_instance.h b/src/backenddb/pg_insert_donau_instance.h @@ -31,6 +31,7 @@ * Insert information about a Donau charity instance. * * @param cls closure + * @param donau_url URL of the Donau * @param charity structure containing information about the charity * @param charity_id unique identifier for the charity * @return transaction status code diff --git a/src/backenddb/pg_insert_login_token.h b/src/backenddb/pg_insert_login_token.h @@ -35,6 +35,7 @@ * @param creation_time the current time * @param expiration_time when does the token expire * @param validity_scope scope of the token + * @param description human-readable description of the token * @return database result code */ enum GNUNET_DB_QueryStatus diff --git a/src/backenddb/pg_lookup_order_charity.c b/src/backenddb/pg_lookup_order_charity.c @@ -17,7 +17,7 @@ <http://www.gnu.org/licenses/> */ /** - * @file backenddb/pg_lookup_donau_charity.c + * @file backenddb/pg_lookup_order_charity.c * @brief Implementation for retrieving Donau charity_id and corresponding private key * by Donau URL. * @author Bohdan Potuzhnyi @@ -33,13 +33,19 @@ #include "pg_helper.h" /** - * Implementation of #TMH_PG_lookup_donau_charity. + * Looking for charity information based on the Donau URL * * This function: * 1. Finds the relevant row in merchant_donau_instances by matching donau_url. * 2. Joins to merchant_instances by comparing charity_pub_key = merchant_pub. * 3. Joins to merchant_keys by matching the merchant_serial from merchant_instances, * retrieving merchant_priv (the private key). + * + * @param cls closure (must be a PostgresClosure) + * @param donau_url the Donau instance URL to look up + * @param[out] charity_id the resulting charity ID, if found + * @param[out] charity_priv the resulting private key, if found + * @return database result code */ enum GNUNET_DB_QueryStatus TMH_PG_lookup_order_charity ( @@ -63,16 +69,16 @@ TMH_PG_lookup_order_charity ( check_connection (pg); - PREPARE(pg, - "lookup_donau_charity", - "SELECT di.charity_id, k.merchant_priv " - "FROM merchant_donau_instances di " - "JOIN merchant_instances mi " - " ON di.charity_pub_key = mi.merchant_pub " - "JOIN merchant_keys k " - " ON mi.merchant_serial = k.merchant_serial " - "WHERE di.donau_url=$1" - ";"); + PREPARE (pg, + "lookup_donau_charity", + "SELECT di.charity_id, k.merchant_priv " + "FROM merchant_donau_instances di " + "JOIN merchant_instances mi " + " ON di.charity_pub_key = mi.merchant_pub " + "JOIN merchant_keys k " + " ON mi.merchant_serial = k.merchant_serial " + "WHERE di.donau_url=$1" + ";"); return GNUNET_PQ_eval_prepared_singleton_select (pg->conn, "lookup_donau_charity", diff --git a/src/backenddb/pg_lookup_order_charity.h b/src/backenddb/pg_lookup_order_charity.h @@ -17,15 +17,15 @@ <http://www.gnu.org/licenses/> */ /** - * @file backenddb/pg_lookup_donau_charity.h + * @file backenddb/pg_lookup_order_charity.h * @brief Header for retrieving Donau charity_id and corresponding private key * by Donau URL. * @author Bohdan Potuzhnyi * @author Vlada Svirsh */ -#ifndef PG_LOOKUP_DONAU_CHARITY_H -#define PG_LOOKUP_DONAU_CHARITY_H +#ifndef PG_LOOKUP_ORDER_CHARITY_H +#define PG_LOOKUP_ORDER_CHARITY_H #include "platform.h" #include <taler/taler_error_codes.h> @@ -52,4 +52,4 @@ TMH_PG_lookup_order_charity ( uint64_t *charity_id, struct DONAU_CharityPrivateKeyP *charity_priv); -#endif /* PG_LOOKUP_DONAU_CHARITY_H */ -\ No newline at end of file +#endif /* PG_LOOKUP_ORDER_CHARITY_H */ +\ No newline at end of file diff --git a/src/testing/testing_api_cmd_delete_donau_instances.c b/src/testing/testing_api_cmd_delete_donau_instances.c @@ -15,7 +15,7 @@ */ /** - * @file testing_api_cmd_delete_donau.c + * @file testing_api_cmd_delete_donau_instances.c * @brief Command to test DELETE /donau/$charity_id request * @author Bohdan Potuzhnyi * @author Vlada Svirsh diff --git a/src/testing/testing_api_cmd_post_donau_instances.c b/src/testing/testing_api_cmd_post_donau_instances.c @@ -17,7 +17,7 @@ <http://www.gnu.org/licenses/> */ /** - * @file testing_api_cmd_post_donau.c + * @file testing_api_cmd_post_donau_instances.c * @brief command to test POST /donau request * @author Bohdan Potuzhnyi * @author Vlada Svirsh