From 730d8c893cdf272f1a5e2a7f796102d670a28c47 Mon Sep 17 00:00:00 2001
From: Christian Grothoff <christian@grothoff.org>
Date: Sat, 12 Feb 2022 12:35:03 +0100
Subject: -more doxygen fixes

---
 src/exchange/taler-exchange-httpd_melt.h |  6 ++---
 src/include/taler_crypto_lib.h           |  2 +-
 src/include/taler_exchange_service.h     |  5 ++--
 src/include/taler_signatures.h           |  1 -
 src/include/taler_testing_lib.h          |  7 +++---
 src/include/taler_util.h                 |  1 +
 src/lib/auditor_api_handle.c             | 41 +-------------------------------
 src/lib/exchange_api_deposit.c           |  1 +
 src/lib/exchange_api_refresh_common.h    |  4 ++--
 src/lib/exchange_api_refreshes_reveal.c  | 11 ++++-----
 src/lib/exchange_api_withdraw.c          |  3 ++-
 src/pq/pq_result_helper.c                | 10 ++++----
 12 files changed, 27 insertions(+), 65 deletions(-)

(limited to 'src')

diff --git a/src/exchange/taler-exchange-httpd_melt.h b/src/exchange/taler-exchange-httpd_melt.h
index 0edaf2475..b15fd07c7 100644
--- a/src/exchange/taler-exchange-httpd_melt.h
+++ b/src/exchange/taler-exchange-httpd_melt.h
@@ -30,10 +30,10 @@
 
 /**
  * Handle a "/coins/$COIN_PUB/melt" request.  Parses the request into the JSON
- * components and then hands things of to #check_for_denomination_key() to
+ * components and then hands things of to #check_melt_valid() to
  * validate the melted coins, the signature and execute the melt using
- * handle_melt().
-
+ * melt_transaction().
+ *
  * @param connection the MHD connection to handle
  * @param coin_pub public key of the coin
  * @param root uploaded JSON data
diff --git a/src/include/taler_crypto_lib.h b/src/include/taler_crypto_lib.h
index 959169cfa..f007d67af 100644
--- a/src/include/taler_crypto_lib.h
+++ b/src/include/taler_crypto_lib.h
@@ -2086,7 +2086,7 @@ TALER_CRYPTO_helper_esign_sign_ (
 
 
 /**
- * Ask the helper to revoke the public key @param exchange_pub .
+ * Ask the helper to revoke the public key @a exchange_pub .
  * Will cause the helper to tell all clients that the key is now unavailable,
  * and to create a replacement key.
  *
diff --git a/src/include/taler_exchange_service.h b/src/include/taler_exchange_service.h
index 72990dc3d..af06d149a 100644
--- a/src/include/taler_exchange_service.h
+++ b/src/include/taler_exchange_service.h
@@ -2039,8 +2039,7 @@ struct TALER_EXCHANGE_GetDepositResponse
  * Function called with detailed wire transfer data.
  *
  * @param cls closure
- * @param hr HTTP response data
- * @param dd details about the deposit (NULL on errors)
+ * @param dr details about the deposit response
  */
 typedef void
 (*TALER_EXCHANGE_DepositGetCallback)(
@@ -2319,7 +2318,7 @@ struct TALER_EXCHANGE_KycStatus
 
       /**
        * Signature of purpose
-       * #TALER_SIGNATURE_ACCOUNT_SETUP_SUCCESS affirming
+       * #TALER_SIGNATURE_EXCHANGE_ACCOUNT_SETUP_SUCCESS affirming
        * the successful KYC process.
        */
       struct TALER_ExchangeSignatureP exchange_sig;
diff --git a/src/include/taler_signatures.h b/src/include/taler_signatures.h
index fc10f9a13..17ed4b57a 100644
--- a/src/include/taler_signatures.h
+++ b/src/include/taler_signatures.h
@@ -164,7 +164,6 @@
  */
 #define TALER_SIGNATURE_EXCHANGE_AFFIRM_DENOM_UNKNOWN 1042
 
-
 /**
  * Signature where the Exchange confirms that it does not consider a denomination valid for the given operation
  * at this time.
diff --git a/src/include/taler_testing_lib.h b/src/include/taler_testing_lib.h
index 271302ae2..69cb9f68f 100644
--- a/src/include/taler_testing_lib.h
+++ b/src/include/taler_testing_lib.h
@@ -998,10 +998,11 @@ TALER_TESTING_cmd_bank_debits (const char *label,
 /**
  * Create transfer command.
  *
- * @param label command label.
- * @param amount amount to transfer.
+ * @param label command label
+ * @param amount amount to transfer
  * @param auth authentication data to use
- * @param payto_credit_account which account receives money.
+ * @param payto_debit_account which account to withdraw money from
+ * @param payto_credit_account which account receives money
  * @param wtid wire transfer identifier to use
  * @param exchange_base_url exchange URL to use
  * @return the command.
diff --git a/src/include/taler_util.h b/src/include/taler_util.h
index 64df12a7c..b7b748698 100644
--- a/src/include/taler_util.h
+++ b/src/include/taler_util.h
@@ -131,6 +131,7 @@ TALER_b2s (const void *buf,
 /**
  * Obtain denomination amount from configuration file.
  *
+ * @param cfg configuration to extract data from
  * @param section section of the configuration to access
  * @param option option of the configuration to access
  * @param[out] denom set to the amount found in configuration
diff --git a/src/lib/auditor_api_handle.c b/src/lib/auditor_api_handle.c
index 1d5522141..f7d7f9a77 100644
--- a/src/lib/auditor_api_handle.c
+++ b/src/lib/auditor_api_handle.c
@@ -365,12 +365,6 @@ version_completed_cb (void *cls,
 /* ********************* library internal API ********* */
 
 
-/**
- * Get the context of a auditor.
- *
- * @param h the auditor handle to query
- * @return ctx context to execute jobs in
- */
 struct GNUNET_CURL_Context *
 TALER_AUDITOR_handle_to_context_ (struct TALER_AUDITOR_Handle *h)
 {
@@ -378,13 +372,7 @@ TALER_AUDITOR_handle_to_context_ (struct TALER_AUDITOR_Handle *h)
 }
 
 
-/**
- * Check if the handle is ready to process requests.
- *
- * @param h the auditor handle to query
- * @return #GNUNET_YES if we are ready, #GNUNET_NO if not
- */
-int
+enum GNUNET_GenericReturnValue
 TALER_AUDITOR_handle_is_ready_ (struct TALER_AUDITOR_Handle *h)
 {
   GNUNET_log (GNUNET_ERROR_TYPE_INFO,
@@ -396,13 +384,6 @@ TALER_AUDITOR_handle_is_ready_ (struct TALER_AUDITOR_Handle *h)
 }
 
 
-/**
- * Obtain the URL to use for an API request.
- *
- * @param h handle for the auditor
- * @param path Taler API path (i.e. "/deposit-confirmation")
- * @return the full URL to use with cURL
- */
 char *
 TALER_AUDITOR_path_to_url_ (struct TALER_AUDITOR_Handle *h,
                             const char *path)
@@ -417,21 +398,6 @@ TALER_AUDITOR_path_to_url_ (struct TALER_AUDITOR_Handle *h,
 /* ********************* public API ******************* */
 
 
-/**
- * Initialise a connection to the auditor. Will connect to the
- * auditor and obtain information about the auditor's master public
- * key and the auditor's auditor.  The respective information will
- * be passed to the @a version_cb once available, and all future
- * interactions with the auditor will be checked to be signed
- * (where appropriate) by the respective master key.
- *
- * @param ctx the context
- * @param url HTTP base URL for the auditor
- * @param version_cb function to call with the
- *        auditor's version information
- * @param version_cb_cls closure for @a version_cb
- * @return the auditor handle; NULL upon error
- */
 struct TALER_AUDITOR_Handle *
 TALER_AUDITOR_connect (struct GNUNET_CURL_Context *ctx,
                        const char *url,
@@ -515,11 +481,6 @@ request_version (void *cls)
 }
 
 
-/**
- * Disconnect from the auditor
- *
- * @param auditor the auditor handle
- */
 void
 TALER_AUDITOR_disconnect (struct TALER_AUDITOR_Handle *auditor)
 {
diff --git a/src/lib/exchange_api_deposit.c b/src/lib/exchange_api_deposit.c
index fa3d75f5d..7ff596518 100644
--- a/src/lib/exchange_api_deposit.c
+++ b/src/lib/exchange_api_deposit.c
@@ -461,6 +461,7 @@ handle_deposit_finished (void *cls,
  * @param amount the amount to be deposited
  * @param h_wire hash of the merchant’s account details
  * @param h_contract_terms hash of the contact of the merchant with the customer (further details are never disclosed to the exchange)
+ * @param ech hash over contract extensions
  * @param coin_pub coin’s public key
  * @param denom_sig exchange’s unblinded signature of the coin
  * @param denom_pub denomination key with which the coin is signed
diff --git a/src/lib/exchange_api_refresh_common.h b/src/lib/exchange_api_refresh_common.h
index 70085a5b6..923fb76c4 100644
--- a/src/lib/exchange_api_refresh_common.h
+++ b/src/lib/exchange_api_refresh_common.h
@@ -122,7 +122,7 @@ struct MeltData
  * @param rms secret internals of the refresh-reveal operation
  * @param rd refresh data with the characteristics of the operation
  * @param alg_values contributions from the exchange into the melt
- * @param[out] rd where to write the derived melt data
+ * @param[out] md where to write the derived melt data
  */
 enum GNUNET_GenericReturnValue
 TALER_EXCHANGE_get_melt_data_ (
@@ -136,7 +136,7 @@ TALER_EXCHANGE_get_melt_data_ (
  * Free all information associated with a melting session.  Note
  * that we allow the melting session to be only partially initialized,
  * as we use this function also when freeing melt data that was not
- * fully initialized (i.e. due to failures in #TALER_EXCHANGE_deserialize_melt_data_()).
+ * fully initialized.
  *
  * @param[in] md melting data to release, the pointer itself is NOT
  *           freed (as it is typically not allocated by itself)
diff --git a/src/lib/exchange_api_refreshes_reveal.c b/src/lib/exchange_api_refreshes_reveal.c
index 2fc02d330..0b44aa355 100644
--- a/src/lib/exchange_api_refreshes_reveal.c
+++ b/src/lib/exchange_api_refreshes_reveal.c
@@ -89,18 +89,17 @@ struct TALER_EXCHANGE_RefreshesRevealHandle
 
 
 /**
- * We got a 200 OK response for the /refreshes/$RCH/reveal operation.
- * Extract the coin signatures and return them to the caller.
- * The signatures we get from the exchange is for the blinded value.
- * Thus, we first must unblind them and then should verify their
- * validity.
+ * We got a 200 OK response for the /refreshes/$RCH/reveal operation.  Extract
+ * the coin signatures and return them to the caller.  The signatures we get
+ * from the exchange is for the blinded value.  Thus, we first must unblind
+ * them and then should verify their validity.
  *
  * If everything checks out, we return the unblinded signatures
  * to the application via the callback.
  *
  * @param rrh operation handle
  * @param json reply from the exchange
- * @param[out] sigs array of length `num_fresh_coins`, initialized to contain the coin private keys
+ * @param[out] coin_privs array of length `num_fresh_coins`, initialized to contain the coin private keys
  * @param[out] sigs array of length `num_fresh_coins`, initialized to contain signatures
  * @return #GNUNET_OK on success, #GNUNET_SYSERR on errors
  */
diff --git a/src/lib/exchange_api_withdraw.c b/src/lib/exchange_api_withdraw.c
index 743fea4bb..c832699a2 100644
--- a/src/lib/exchange_api_withdraw.c
+++ b/src/lib/exchange_api_withdraw.c
@@ -185,7 +185,8 @@ handle_reserve_withdraw_finished (
 /**
  * Function called when stage 1 of CS withdraw is finished (request r_pub's)
  *
- * @param cls
+ * @param cls the `struct TALER_EXCHANGE_WithdrawHandle`
+ * @param csrr replies from the /csr request
  */
 static void
 withdraw_cs_stage_two_callback (void *cls,
diff --git a/src/pq/pq_result_helper.c b/src/pq/pq_result_helper.c
index 92022d61e..1115a130c 100644
--- a/src/pq/pq_result_helper.c
+++ b/src/pq/pq_result_helper.c
@@ -357,7 +357,7 @@ TALER_PQ_result_spec_json (const char *name,
  *
  * @param cls closure
  * @param result where to extract data from
- * @param int row to extract data from
+ * @param row the row to extract data from
  * @param fname name (or prefix) of the fields to extract from
  * @param[in,out] dst_size where to store size of result, may be NULL
  * @param[out] dst where to store the result
@@ -480,7 +480,7 @@ TALER_PQ_result_spec_denom_pub (const char *name,
  *
  * @param cls closure
  * @param result where to extract data from
- * @param int row to extract data from
+ * @param row the row to extract data from
  * @param fname name (or prefix) of the fields to extract from
  * @param[in,out] dst_size where to store size of result, may be NULL
  * @param[out] dst where to store the result
@@ -607,7 +607,7 @@ TALER_PQ_result_spec_denom_sig (const char *name,
  *
  * @param cls closure
  * @param result where to extract data from
- * @param int row to extract data from
+ * @param row the row to extract data from
  * @param fname name (or prefix) of the fields to extract from
  * @param[in,out] dst_size where to store size of result, may be NULL
  * @param[out] dst where to store the result
@@ -735,7 +735,7 @@ TALER_PQ_result_spec_blinded_denom_sig (
  *
  * @param cls closure
  * @param result where to extract data from
- * @param int row to extract data from
+ * @param row the row to extract data from
  * @param fname name (or prefix) of the fields to extract from
  * @param[in,out] dst_size where to store size of result, may be NULL
  * @param[out] dst where to store the result
@@ -860,7 +860,7 @@ TALER_PQ_result_spec_blinded_planchet (
  *
  * @param cls closure
  * @param result where to extract data from
- * @param int row to extract data from
+ * @param row row to extract data from
  * @param fname name (or prefix) of the fields to extract from
  * @param[in,out] dst_size where to store size of result, may be NULL
  * @param[out] dst where to store the result
-- 
cgit v1.2.3