commit a65bd1488f20f1cf42f955b10e7ce191c1976f1b
parent d03fcfad61fddb5a01ed6b2193fce67cecdf67bf
Author: Florian Dold <dold@taler.net>
Date: Mon, 7 Sep 2026 22:04:10 +0200
exchange docs: keep function parameter documentation in headers
Remove duplicate implementation comments that Doxygen combines with the
header documentation. Preserve the key decoding cleanup requirement in
the header alongside the rest of the function contract.
Diffstat:
10 files changed, 3 insertions(+), 96 deletions(-)
diff --git a/src/exchangedb/commit.c b/src/exchangedb/commit.c
@@ -23,12 +23,6 @@
#include "helper.h"
-/**
- * Commit the current transaction of a database connection.
- *
- * @param pg the database context
- * @return final transaction status
- */
enum GNUNET_DB_QueryStatus
TALER_EXCHANGEDB_commit (struct TALER_EXCHANGEDB_PostgresContext *pg)
{
diff --git a/src/exchangedb/do_reserve_purse.c b/src/exchangedb/do_reserve_purse.c
@@ -23,23 +23,6 @@
#include "helper.h"
-/**
- * Function called insert request to merge a purse into a reserve by the
- * respective purse merge key. The purse must not have been merged into a
- * different reserve.
- *
- * @param pg the database context
- * @param purse_pub purse to merge
- * @param merge_sig signature affirming the merge
- * @param merge_timestamp time of the merge
- * @param reserve_sig signature of the reserve affirming the merge
- * @param purse_fee amount to charge the reserve for the purse creation, NULL to use the quota
- * @param reserve_pub public key of the reserve to credit
- * @param[out] in_conflict set to true if @a purse_pub was merged into a different reserve already
- * @param[out] no_reserve set to true if @a reserve_pub is not a known reserve
- * @param[out] insufficient_funds set to true if @a reserve_pub has insufficient capacity to create another purse
- * @return transaction status code
- */
enum GNUNET_DB_QueryStatus
TALER_EXCHANGEDB_do_reserve_purse (
struct TALER_EXCHANGEDB_PostgresContext *pg,
diff --git a/src/exchangedb/drop_tables.c b/src/exchangedb/drop_tables.c
@@ -23,12 +23,6 @@
#include "helper.h"
-/**
- * Drop all Taler tables. This should only be used by testcases.
- *
- * @param pg the database context
- * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure
- */
enum GNUNET_GenericReturnValue
TALER_EXCHANGEDB_drop_tables (
struct TALER_EXCHANGEDB_PostgresContext *pg)
diff --git a/src/exchangedb/event_listen.c b/src/exchangedb/event_listen.c
@@ -22,17 +22,6 @@
#include "exchange-database/event_listen.h"
#include "helper.h"
-/**
- * Register callback to be invoked on events of type @a es.
- *
- * @param pg the database context
- * @param timeout how long until to generate a timeout event
- * @param es specification of the event to listen for
- * @param cb function to call when the event happens, possibly
- * multiple times (until cancel is invoked)
- * @param cb_cls closure for @a cb
- * @return handle useful to cancel the listener
- */
struct GNUNET_DB_EventHandler *
TALER_EXCHANGEDB_event_listen (struct TALER_EXCHANGEDB_PostgresContext *pg,
struct GNUNET_TIME_Relative timeout,
diff --git a/src/exchangedb/get_wire_fee_by_time.c b/src/exchangedb/get_wire_fee_by_time.c
@@ -100,22 +100,6 @@ wire_fee_by_time_helper (void *cls,
}
-/**
- * Lookup information about known wire fees. Finds all applicable
- * fees in the given range. If they are identical, returns the
- * respective @a fees. If any of the fees
- * differ between @a start_time and @a end_time, the transaction
- * succeeds BUT returns an invalid amount for both fees.
- *
- * @param pg the database context
- * @param wire_method the wire method to lookup fees for
- * @param start_time starting time of fee
- * @param end_time end time of fee
- * @param[out] fees wire fees for that time period; if
- * different fees exists within this time
- * period, an 'invalid' amount is returned.
- * @return transaction status code
- */
enum GNUNET_DB_QueryStatus
TALER_EXCHANGEDB_get_wire_fee_by_time (
struct TALER_EXCHANGEDB_PostgresContext *pg,
diff --git a/src/exchangedb/inject_auditor_triggers.c b/src/exchangedb/inject_auditor_triggers.c
@@ -26,14 +26,6 @@
#include "exchange-database/inject_auditor_triggers.h"
-/**
- * Function called to inject auditor triggers into the database, triggering
- * the real-time auditor upon relevant INSERTs.
- *
- * @param pg the database context
- * @return #GNUNET_OK on success,
- * #GNUNET_SYSERR on DB errors
- */
enum GNUNET_GenericReturnValue
TALER_EXCHANGEDB_inject_auditor_triggers (
struct TALER_EXCHANGEDB_PostgresContext *pg)
diff --git a/src/exchangedb/iterate_active_signkeys.c b/src/exchangedb/iterate_active_signkeys.c
@@ -91,16 +91,6 @@ signkeys_cb_helper (void *cls,
}
-/**
- * Function called to invoke @a cb on every non-revoked exchange signing key
- * that has been signed by the master key. Revoked and (for signing!)
- * expired keys are skipped. Runs in its own read-only transaction.
- *
- * @param pg the database context
- * @param cb function to call on each signing key
- * @param cb_cls closure for @a cb
- * @return transaction status code
- */
enum GNUNET_DB_QueryStatus
TALER_EXCHANGEDB_iterate_active_signkeys (struct
TALER_EXCHANGEDB_PostgresContext *pg,
diff --git a/src/exchangedb/iterate_denomination_info.c b/src/exchangedb/iterate_denomination_info.c
@@ -134,14 +134,6 @@ domination_cb_helper (void *cls,
}
-/**
- * Fetch information about all known denomination keys.
- *
- * @param pg the database context
- * @param cb function to call on each denomination key
- * @param cb_cls closure for @a cb
- * @return transaction status code
- */
enum GNUNET_DB_QueryStatus
TALER_EXCHANGEDB_iterate_denomination_info (struct
TALER_EXCHANGEDB_PostgresContext *pg
diff --git a/src/lib/exchange_api_handle.c b/src/lib/exchange_api_handle.c
@@ -895,19 +895,6 @@ parse_wads (const json_t *wads_array,
}
-/**
- * Decode the JSON in @a resp_obj from the /keys response
- * and store the data in the @a key_data.
- *
- * @param[in] resp_obj JSON object to parse
- * @param check_sig true if we should check the signature
- * @param[out] key_data where to store the results we decoded
- * @param[out] vc where to store version compatibility data
- * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
- * (malformed JSON); on #GNUNET_SYSERR, the @a key_data
- * structure may be partially initialized and must still
- * be released using #TALER_EXCHANGE_keys_decref()!
- */
enum GNUNET_GenericReturnValue
TALER_EXCHANGE_decode_keys_json_ (
const json_t *resp_obj,
diff --git a/src/lib/exchange_api_handle.h b/src/lib/exchange_api_handle.h
@@ -69,7 +69,9 @@ TALER_EXCHANGE_get_auditors_for_dc_ (
* @param[out] key_data where to store the results we decoded
* @param[out] vc where to store version compatibility data
* @return #GNUNET_OK on success, #GNUNET_SYSERR on error
- * (malformed JSON)
+ * (malformed JSON); on #GNUNET_SYSERR, the @a key_data
+ * structure may be partially initialized and must still
+ * be released using #TALER_EXCHANGE_keys_decref()!
*/
enum GNUNET_GenericReturnValue
TALER_EXCHANGE_decode_keys_json_ (
