-fix misc doxygen warnings, code clean up

contrib/microhttpd.tag

@@ -22,6 +22,12 @@
       <anchorfile>microhttpd.h</anchorfile>
       <arglist></arglist>
     </member>
+    <member kind="define">
+      <type>#define</type>
+      <name>MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS</name>
+      <anchorfile>microhttpd.h</anchorfile>
+      <arglist></arglist>
+    </member>
     <member kind="define">
       <type>#define</type>
       <name>MHD_HTTP_BAD_REQUEST</name>

src/auditor/taler-helper-auditor-coins.c

@@ -1207,6 +1207,7 @@ check_known_coin (
  * @param cls closure
  * @param rowid unique serial ID for the refresh session in our DB
  * @param denom_pub denomination public key of @a coin_pub
+ * @param h_age_commitment hash of the age commitment for the coin
  * @param coin_pub public key of the coin
  * @param coin_sig signature from the coin
  * @param amount_with_fee amount that was deposited including fee
@@ -2281,7 +2282,7 @@ recoup_refresh_cb (void *cls,
  *
  * @param cls closure, NULL
  * @param denom_pub public key, sometimes NULL (!)
- * @param validity issuing information with value, fees and other info about the denomination.
+ * @param issue issuing information with value, fees and other info about the denomination.
  */
 static void
 check_denomination (

src/auditor/taler-helper-auditor-reserves.c

@@ -1262,7 +1262,6 @@ verify_reserve_balance (void *cls,
  * @param rowid unique serial ID for the deposit in our DB
  * @param deposit deposit details
  * @param reserve_pub which reserve is the purse merged into, NULL if unknown
- * @param auditor_balance balance of the purse calculated by auditor
  * @param flags purse flags
  * @param auditor_balance purse balance (according to the
  *          auditor during auditing)
@@ -1530,6 +1529,16 @@ handle_purse_merged (
  *
  * @param cls closure
  * @param rowid unique serial ID for the deposit in our DB
+ * @param reserve_pub reserve affected by the merge
+ * @param purse_pub purse being merged
+ * @param h_contract_terms hash over contract of the purse
+ * @param purse_expiration when would the purse expire
+ * @param amount total amount in the purse
+ * @param min_age minimum age of all coins deposited into the purse
+ * @param flags how was the purse created
+ * @param purse_fee if a purse fee was paid, how high is it
+ * @param merge_timestamp when was the merge approved
+ * @param reserve_sig signature by reserve approving the merge
  * @return #GNUNET_OK to continue to iterate, #GNUNET_SYSERR to stop
  */
 static enum GNUNET_GenericReturnValue
@@ -1604,6 +1613,10 @@ handle_account_merged (
  *
  * @param cls closure
  * @param rowid unique serial ID for the deposit in our DB
+ * @param history_fee fee paid for the request
+ * @param ts timestamp of the request
+ * @param reserve_pub reserve history was requested for
+ * @param reserve_sig signature approving the @a history_fee
  * @return #GNUNET_OK to continue to iterate, #GNUNET_SYSERR to stop
  */
 static enum GNUNET_GenericReturnValue

src/auditordb/plugin_auditordb_postgres.c

@@ -2068,6 +2068,8 @@ postgres_insert_reserve_summary (
  * @param reserve_balance amount stored in the reserve
  * @param withdraw_fee_balance amount the exchange gained in withdraw fees
  *                             due to withdrawals from this reserve
+ * @param purse_fee_balance amount the exchange gained in purse fees
+ * @param history_fee_balance amount the exchange gained in history fees
  * @return transaction status code
  */
 static enum GNUNET_DB_QueryStatus

src/exchange-tools/taler-exchange-offline.c

@@ -729,7 +729,7 @@ do_shutdown (void *cls)
       GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
                   "Aborting incomplete extensions signature upload #%u\n",
                   (unsigned int) uer->idx);
-      TALER_EXCHANGE_post_management_extensions_cancel (uer->h);
+      TALER_EXCHANGE_management_post_extensions_cancel (uer->h);
       GNUNET_CONTAINER_DLL_remove (uer_head,
                                    uer_tail,
                                    uer);

src/exchange/taler-exchange-httpd.c

@@ -426,7 +426,7 @@ handle_post_reserves (struct TEH_RequestContext *rc,
 /**
  * Signature of functions that handle operations on purses.
  *
- * @param rc request context
+ * @param connection HTTP request handle
  * @param purse_pub the public key of the purse
  * @param root uploaded JSON data
  * @return MHD result code

src/exchange/taler-exchange-httpd_keys.h

@@ -246,7 +246,6 @@ TEH_keys_denomination_by_hash2 (
  *
  * @param h_denom_pub hash of the public key to use to sign
  * @param bp blinded planchet to sign
- * @param is_melt should we use the KDF for melting?
  * @param[out] bs set to the blind signature on success
  * @return #TALER_EC_NONE on success
  */
@@ -263,7 +262,6 @@ TEH_keys_denomination_sign_withdraw (
  *
  * @param h_denom_pub hash of the public key to use to sign
  * @param bp blinded planchet to sign
- * @param is_melt should we use the KDF for melting?
  * @param[out] bs set to the blind signature on success
  * @return #TALER_EC_NONE on success
  */

src/exchange/taler-exchange-httpd_purses_create.c

@@ -443,8 +443,8 @@ create_transaction (void *cls,
  * Parse a coin and check signature of the coin and the denomination
  * signature over the coin.
  *
- * @param[in,out] our HTTP connection
+ * @param[in,out] connection our HTTP connection
- * @param[in,out] request context
+ * @param[in,out] pcc request context
  * @param[out] coin coin to initialize
  * @param jcoin coin to parse
  * @return #GNUNET_OK on success, #GNUNET_NO if an error was returned,

src/exchange/taler-exchange-httpd_purses_deposit.c

@@ -287,8 +287,8 @@ deposit_transaction (void *cls,
  * Parse a coin and check signature of the coin and the denomination
  * signature over the coin.
  *
- * @param[in,out] our HTTP connection
+ * @param[in,out] connection our HTTP connection
- * @param[in,out] request context
+ * @param[in,out] pcc request context
  * @param[out] coin coin to initialize
  * @param jcoin coin to parse
  * @return #GNUNET_OK on success, #GNUNET_NO if an error was returned,

src/exchange/taler-exchange-httpd_recoup-refresh.c

@@ -166,6 +166,7 @@ recoup_refresh_transaction (void *cls,
  * @param exchange_vals values contributed by the exchange
  *         during refresh
  * @param coin_bks blinding data of the coin (to be checked)
+ * @param nonce withdraw nonce (if CS is used)
  * @param coin_sig signature of the coin
  * @return MHD result code
  */

src/exchange/taler-exchange-httpd_recoup.c

@@ -169,6 +169,7 @@ recoup_transaction (void *cls,
  * @param exchange_vals values contributed by the exchange
  *         during withdrawal
  * @param coin_bks blinding data of the coin (to be checked)
+ * @param nonce coin's nonce if CS is used
  * @param coin_sig signature of the coin
  * @return MHD result code
  */

src/exchange/taler-exchange-httpd_reserves_history.c

@@ -80,7 +80,7 @@ struct ReserveHistoryContext
  * Send reserve history to client.
  *
  * @param connection connection to the client
- * @param rh reserve history to return
+ * @param rhc reserve history to return
  * @return MHD result code
  */
 static MHD_RESULT

src/exchange/taler-exchange-httpd_reserves_purse.h

@@ -33,7 +33,7 @@
  * will ultimately lead to the "purses create" being executed, or rejected.
  *
  * @param rc request context
- * @param purse_pub public key of the purse
+ * @param reserve_pub public key of the reserve
  * @param root uploaded JSON data
  * @return MHD result code
  */

src/exchange/taler-exchange-httpd_reserves_status.c

@@ -69,7 +69,7 @@ struct ReserveStatusContext
  * Send reserve status to client.
  *
  * @param connection connection to the client
- * @param rh reserve history to return
+ * @param rhc reserve history to return
  * @return MHD result code
  */
 static MHD_RESULT

src/exchangedb/plugin_exchangedb_postgres.c

@@ -6188,6 +6188,7 @@ postgres_do_deposit (
  * of the coin and possibly persisting the melt details.
  *
  * @param cls the `struct PostgresClosure` with the plugin-specific state
+ * @param rms client-contributed input for CS denominations that must be checked for idempotency, or NULL for non-CS withdrawals
  * @param[in,out] refresh refresh operation details; the noreveal_index
  *                is set in case the coin was already melted before
  * @param known_coin_id row of the coin in the known_coins table
@@ -9694,12 +9695,14 @@ postgres_insert_wire_fee (void *cls,
  * Insert global fee data into database.
  *
  * @param cls closure
- * @param start_date when does the fee go into effect
+ * @param start_date when does the fees go into effect
+ * @param end_date when does the fees end being valid
  * @param fees how high is are the global fees
  * @param purse_timeout when do purses time out
  * @param kyc_timeout when do reserves without KYC time out
  * @param history_expiration how long are account histories preserved
- * @param purse_account_limit how many purses are free per account * @param master_sig signature over the above by the exchange master key
+ * @param purse_account_limit how many purses are free per account
+ * @param master_sig signature over the above by the exchange master key
  * @return transaction status code
  */
 static enum GNUNET_DB_QueryStatus
@@ -15293,7 +15296,7 @@ postgres_select_purse_request (
  * @param[out] in_conflict set to true if the meta data
  *             conflicts with an existing purse;
  *             in this case, the return value will be
- *             #GNUNET_DB_STATUS_SUCCESS_ONE despite the failure
+ *             #GNUNET_DB_STATUS_SUCCESS_ONE_RESULT despite the failure
  * @return transaction status code
  */
 static enum GNUNET_DB_QueryStatus
@@ -15541,7 +15544,9 @@ postgres_select_purse_by_merge_pub (
  * @param[out] balance_ok set to false if the coin's
  *        remaining balance is below @a amount;
  *             in this case, the return value will be
- *             #GNUNET_DB_STATUS_SUCCESS_ONE despite the failure
+ *             #GNUNET_DB_STATUS_SUCCESS_ONE_RESULT despite the failure
+ * @param[out] conflict set to true if the deposit failed due to a conflict (coin already spent,
+ *             or deposited into this purse with a different amount)
  * @return transaction status code
  */
 static enum GNUNET_DB_QueryStatus
@@ -15891,7 +15896,7 @@ postgres_insert_history_request (
   const struct TALER_ReservePublicKeyP *reserve_pub,
   const struct TALER_ReserveSignatureP *reserve_sig,
   struct GNUNET_TIME_Timestamp request_timestamp,
-  const struct TALER_Amount *history,
+  const struct TALER_Amount *history_fee,
   bool *balance_ok,
   bool *idempotent)
 {
@@ -15900,7 +15905,7 @@ postgres_insert_history_request (
     GNUNET_PQ_query_param_auto_from_type (reserve_pub),
     GNUNET_PQ_query_param_auto_from_type (reserve_sig),
     GNUNET_PQ_query_param_timestamp (&request_timestamp),
-    TALER_PQ_query_param_amount (history),
+    TALER_PQ_query_param_amount (history_fee),
     GNUNET_PQ_query_param_end
   };
   struct GNUNET_PQ_ResultSpec rs[] = {

src/include/taler_crypto_lib.h

@@ -2872,7 +2872,7 @@ TALER_wallet_purse_status_sign (
  * Verify a purse status request signature.
  *
  * @param purse_pub purse’s public key
- * @param purse_sig the signature made with purpose #TALER_SIGNATURE_WALLET_PURSE_STATUS_REQUEST
+ * @param purse_sig the signature made with purpose #TALER_SIGNATURE_WALLET_PURSE_STATUS
  * @return #GNUNET_OK if the signature is valid
  */
 enum GNUNET_GenericReturnValue
@@ -3155,7 +3155,7 @@ TALER_wallet_deposit_verify (
   const struct TALER_Amount *deposit_fee,
   const struct TALER_MerchantWireHashP *h_wire,
   const struct TALER_PrivateContractHashP *h_contract_terms,
-  const struct TALER_AgeCommitmentHash *h_commitment_hash,
+  const struct TALER_AgeCommitmentHash *h_age_commitment,
   const struct TALER_ExtensionContractHashP *h_extensions,
   const struct TALER_DenominationHashP *h_denom_pub,
   struct GNUNET_TIME_Timestamp wallet_timestamp,
@@ -3389,7 +3389,7 @@ TALER_wallet_reserve_history_verify (
  *
  * @param ts timestamp used
  * @param history_fee how much do we expect to pay
- * @param reserve_pub reserve the history request is for
+ * @param reserve_priv private key of the reserve the history request is for
  * @param[out] reserve_sig resulting signature
  */
 void
@@ -3419,7 +3419,7 @@ TALER_wallet_reserve_status_verify (
  * Create reserve status request signature.
  *
  * @param ts timestamp used
- * @param reserve_pub reserve the status request is for
+ * @param reserve_priv private key of the reserve the status request is for
  * @param[out] reserve_sig resulting signature
  */
 void
@@ -3481,7 +3481,6 @@ TALER_merchant_refund_verify (
  * @param h_contract_terms hash of contract terms
  * @param h_wire hash of the merchant account details
  * @param coin_pub coin to be deposited
- * @param merchant_pub merchant public key
  * @param merchant_priv private key to sign with
  * @param[out] merchant_sig where to write the signature
  */
@@ -3490,15 +3489,15 @@ TALER_merchant_deposit_sign (
   const struct TALER_PrivateContractHashP *h_contract_terms,
   const struct TALER_MerchantWireHashP *h_wire,
   const struct TALER_CoinSpendPublicKeyP *coin_pub,
-  const struct TALER_MerchantPublicKeyP *merchant_pub,
   const struct TALER_MerchantPrivateKeyP *merchant_priv,
   struct TALER_MerchantSignatureP *merchant_sig);
 
+
 /**
  * Verify a deposit.
  *
  * @param merchant merchant public key
- * @param public key of the deposited coin
+ * @param coin_pub public key of the deposited coin
  * @param h_contract_terms hash of contract terms
  * @param h_wire hash of the merchant account details
  * @param merchant_sig signature of the merchant
@@ -3602,6 +3601,7 @@ TALER_exchange_online_deposit_confirmation_sign (
  * @param merchant_pub the public key of the merchant (used to identify the merchant for refund requests)
  * @param pub where to write the public key
  * @param sig where to write the signature
+ * @return #GNUNET_OK if the signature is valid
  */
 enum GNUNET_GenericReturnValue
 TALER_exchange_online_deposit_confirmation_verify (
@@ -3622,9 +3622,13 @@ TALER_exchange_online_deposit_confirmation_verify (
  * Create refund confirmation signature.
  *
  * @param scb function to call to create the signature
- * @param XXX wire transfer subject used
+ * @param h_contract_terms hash of contract being refunded
- * @param[out] pub where to write the public key
+ * @param coin_pub public key of the coin receiving the refund
- * @param[out] sig where to write the signature
+ * @param merchant public key of the merchant that granted the refund
+ * @param rtransaction_id refund transaction ID used by the merchant
+ * @param refund_amount amount refunded
+ * @param[out] pub where to write the exchange public key
+ * @param[out] sig where to write the exchange signature
  */
 enum TALER_ErrorCode
 TALER_exchange_online_refund_confirmation_sign (
@@ -3641,8 +3645,14 @@ TALER_exchange_online_refund_confirmation_sign (
 /**
  * Verify refund confirmation signature.
  *
+ * @param h_contract_terms hash of contract being refunded
+ * @param coin_pub public key of the coin receiving the refund
+ * @param merchant public key of the merchant that granted the refund
+ * @param rtransaction_id refund transaction ID used by the merchant
+ * @param refund_amount amount refunded
  * @param pub where to write the public key
  * @param sig where to write the signature
+ * @return #GNUNET_OK if the signature is valid
  */
 enum GNUNET_GenericReturnValue
 TALER_exchange_online_refund_confirmation_verify (
@@ -3659,9 +3669,10 @@ TALER_exchange_online_refund_confirmation_verify (
  * Create refresh melt confirmation signature.
  *
  * @param scb function to call to create the signature
- * @param XXX
+ * @param rc refresh commitment that identifies the melt operation
- * @param[out] pub where to write the public key
+ * @param noreveal_index gamma cut-and-choose value chosen by the exchange
- * @param[out] sig where to write the signature
+ * @param[out] pub where to write the exchange public key
+ * @param[out] sig where to write the exchange signature
  */
 enum TALER_ErrorCode
 TALER_exchange_online_melt_confirmation_sign (
@@ -3675,8 +3686,11 @@ TALER_exchange_online_melt_confirmation_sign (
 /**
  * Verify refresh melt confirmation signature.
  *
+ * @param rc refresh commitment that identifies the melt operation
+ * @param noreveal_index gamma cut-and-choose value chosen by the exchange
  * @param pub where to write the public key
  * @param sig where to write the signature
+ * @return #GNUNET_OK if the signature is valid
  */
 enum GNUNET_GenericReturnValue
 TALER_exchange_online_melt_confirmation_verify (
@@ -3690,6 +3704,7 @@ TALER_exchange_online_melt_confirmation_verify (
  * Create exchange key set signature.
  *
  * @param scb function to call to create the signature
+ * @param cls closure for @a scb
  * @param timestamp time when the key set was issued
  * @param hc hash over all the keys
  * @param[out] pub where to write the public key
@@ -3712,6 +3727,7 @@ TALER_exchange_online_key_set_sign (
  * @param hc hash over all the keys
  * @param pub where to write the public key
  * @param sig where to write the signature
+ * @return #GNUNET_OK if the signature is valid
  */
 enum GNUNET_GenericReturnValue
 TALER_exchange_online_key_set_verify (
@@ -3746,6 +3762,7 @@ TALER_exchange_online_account_setup_success_sign (
  * @param timestamp time when the KYC was confirmed
  * @param pub where to write the public key
  * @param sig where to write the signature
+ * @return #GNUNET_OK if the signature is valid
  */
 enum GNUNET_GenericReturnValue
 TALER_exchange_online_account_setup_success_verify (
@@ -3755,6 +3772,7 @@ TALER_exchange_online_account_setup_success_verify (
   const struct TALER_ExchangeSignatureP *sig);
 
 
+// FIXME: document!?!
 void
 TALER_exchange_online_wire_deposit_append (
   struct GNUNET_HashContext *hash_context,
@@ -3769,7 +3787,11 @@ TALER_exchange_online_wire_deposit_append (
  * Create wire deposit signature.
  *
  * @param scb function to call to create the signature
- * @param XXX
+ * @param total amount the merchant was credited
+ * @param wire_fee fee charged by the exchange for the wire transfer
+ * @param merchant_pub which merchant was credited
+ * @param payto payto://-URI of the merchant account
+ * @param h_details hash over the aggregation details
  * @param[out] pub where to write the public key
  * @param[out] sig where to write the signature
  */
@@ -3788,8 +3810,14 @@ TALER_exchange_online_wire_deposit_sign (
 /**
  * Verify wire deposit signature.
  *
+ * @param total amount the merchant was credited
+ * @param wire_fee fee charged by the exchange for the wire transfer
+ * @param merchant_pub which merchant was credited
+ * @param h_payto hash of the payto://-URI of the merchant account
+ * @param h_details hash over the aggregation details
  * @param pub where to write the public key
  * @param sig where to write the signature
+ * @return #GNUNET_OK if the signature is valid
  */
 enum GNUNET_GenericReturnValue
 TALER_exchange_online_wire_deposit_verify (
@@ -3806,7 +3834,12 @@ TALER_exchange_online_wire_deposit_verify (
  * Create wire confirmation signature.
  *
  * @param scb function to call to create the signature
- * @param XXX
+ * @param h_wire hash of the merchant's account
+ * @param h_contract_terms hash of the contract
+ * @param wtid wire transfer this deposit was aggregated into
+ * @param coin_pub public key of the deposited coin
+ * @param execution_time when was wire transfer initiated
+ * @param coin_contribution what was @a coin_pub's contribution to the wire transfer
  * @param[out] pub where to write the public key
  * @param[out] sig where to write the signature
  */
@@ -3826,8 +3859,15 @@ TALER_exchange_online_confirm_wire_sign (
 /**
  * Verify confirm wire signature.
  *
+ * @param h_wire hash of the merchant's account
+ * @param h_contract_terms hash of the contract
+ * @param wtid wire transfer this deposit was aggregated into
+ * @param coin_pub public key of the deposited coin
+ * @param execution_time when was wire transfer initiated
+ * @param coin_contribution what was @a coin_pub's contribution to the wire transfer
  * @param pub where to write the public key
  * @param sig where to write the signature
+ * @return #GNUNET_OK if the signature is valid
  */
 enum GNUNET_GenericReturnValue
 TALER_exchange_online_confirm_wire_verify (
@@ -3845,7 +3885,10 @@ TALER_exchange_online_confirm_wire_verify (
  * Create confirm recoup signature.
  *
  * @param scb function to call to create the signature
- * @param XXX
+ * @param timestamp when was the recoup done
+ * @param recoup_amount how much was recouped
+ * @param coin_pub coin that was recouped
+ * @param reserve_pub reserve that was credited
  * @param[out] pub where to write the public key
  * @param[out] sig where to write the signature
  */
@@ -3863,8 +3906,13 @@ TALER_exchange_online_confirm_recoup_sign (
 /**
  * Verify confirm recoup signature.
  *
+ * @param timestamp when was the recoup done
+ * @param recoup_amount how much was recouped
+ * @param coin_pub coin that was recouped
+ * @param reserve_pub reserve that was credited
  * @param pub where to write the public key
  * @param sig where to write the signature
+ * @return #GNUNET_OK if the signature is valid
  */
 enum GNUNET_GenericReturnValue
 TALER_exchange_online_confirm_recoup_verify (
@@ -3880,7 +3928,10 @@ TALER_exchange_online_confirm_recoup_verify (
  * Create confirm recoup refresh signature.
  *
  * @param scb function to call to create the signature
- * @param XXX
+ * @param timestamp when was the recoup done
+ * @param recoup_amount how much was recouped
+ * @param coin_pub coin that was recouped
+ * @param old_coin_pub old coin that was credited
  * @param[out] pub where to write the public key
  * @param[out] sig where to write the signature
  */
@@ -3898,8 +3949,13 @@ TALER_exchange_online_confirm_recoup_refresh_sign (
 /**
  * Verify confirm recoup refresh signature.
  *
+ * @param timestamp when was the recoup done
+ * @param recoup_amount how much was recouped
+ * @param coin_pub coin that was recouped
+ * @param old_coin_pub old coin that was credited
  * @param pub where to write the public key
  * @param sig where to write the signature
+ * @return #GNUNET_OK if the signature is valid
  */
 enum GNUNET_GenericReturnValue
 TALER_exchange_online_confirm_recoup_refresh_verify (
@@ -3915,7 +3971,8 @@ TALER_exchange_online_confirm_recoup_refresh_verify (
  * Create denomination unknown signature.
  *
  * @param scb function to call to create the signature
- * @param XXX
+ * @param timestamp when was the error created
+ * @param h_denom_pub hash of denomination that is unknown
  * @param[out] pub where to write the public key
  * @param[out] sig where to write the signature
  */
@@ -3931,8 +3988,11 @@ TALER_exchange_online_denomination_unknown_sign (
 /**
  * Verify denomination unknown signature.
  *
+ * @param timestamp when was the error created
+ * @param h_denom_pub hash of denomination that is unknown
  * @param pub where to write the public key
  * @param sig where to write the signature
+ * @return #GNUNET_OK if the signature is valid
  */
 enum GNUNET_GenericReturnValue
 TALER_exchange_online_denomination_unknown_verify (
@@ -3946,7 +4006,10 @@ TALER_exchange_online_denomination_unknown_verify (
  * Create denomination expired signature.
  *
  * @param scb function to call to create the signature
- * @param XXX
+ * @param timestamp when was the error created
+ * @param h_denom_pub hash of denomination that is expired
+ * @param op character string describing the operation for which
+ *           the denomination is expired
  * @param[out] pub where to write the public key
  * @param[out] sig where to write the signature
  */
@@ -3963,8 +4026,13 @@ TALER_exchange_online_denomination_expired_sign (
 /**
  * Verify denomination expired signature.
  *
+ * @param timestamp when was the error created
+ * @param h_denom_pub hash of denomination that is expired
+ * @param op character string describing the operation for which
+ *           the denomination is expired
  * @param pub where to write the public key
  * @param sig where to write the signature
+ * @return #GNUNET_OK if the signature is valid
  */
 enum GNUNET_GenericReturnValue
 TALER_exchange_online_denomination_expired_verify (
@@ -4012,6 +4080,7 @@ TALER_exchange_online_reserve_closed_sign (
  * @param reserve_pub public key of the closed reserve
  * @param pub where to write the public key
  * @param sig where to write the signature
+ * @return #GNUNET_OK if the signature is valid
  */
 enum GNUNET_GenericReturnValue
 TALER_exchange_online_reserve_closed_verify (
@@ -4025,6 +4094,7 @@ TALER_exchange_online_reserve_closed_verify (
   const struct TALER_ExchangeSignatureP *sig);
 
 
+// FIXME: document!
 enum TALER_ErrorCode
 TALER_exchange_online_purse_created_sign (
   TALER_ExchangeSignCallback scb,
@@ -4038,6 +4108,7 @@ TALER_exchange_online_purse_created_sign (
   struct TALER_ExchangeSignatureP *sig);
 
 
+// FIXME: document!
 enum GNUNET_GenericReturnValue
 TALER_exchange_online_purse_created_verify (
   struct GNUNET_TIME_Timestamp exchange_time,
@@ -4049,7 +4120,7 @@ TALER_exchange_online_purse_created_verify (
   const struct TALER_ExchangePublicKeyP *pub,
   const struct TALER_ExchangeSignatureP *sig);
 
-
+// FIXME: document!
 enum TALER_ErrorCode
 TALER_exchange_online_purse_merged_sign (
   TALER_ExchangeSignCallback scb,
@@ -4064,6 +4135,7 @@ TALER_exchange_online_purse_merged_sign (
   struct TALER_ExchangeSignatureP *sig);
 
 
+// FIXME: document!
 enum GNUNET_GenericReturnValue
 TALER_exchange_online_purse_merged_verify (
   struct GNUNET_TIME_Timestamp exchange_time,
@@ -4077,6 +4149,7 @@ TALER_exchange_online_purse_merged_verify (
   const struct TALER_ExchangeSignatureP *sig);
 
 
+// FIXME: document!
 enum TALER_ErrorCode
 TALER_exchange_online_purse_status_sign (
   TALER_ExchangeSignCallback scb,
@@ -4087,6 +4160,7 @@ TALER_exchange_online_purse_status_sign (
   struct TALER_ExchangeSignatureP *sig);
 
 
+// FIXME: document!
 enum GNUNET_GenericReturnValue
 TALER_exchange_online_purse_status_verify (
   struct GNUNET_TIME_Timestamp merge_timestamp,
@@ -4780,6 +4854,7 @@ TALER_merchant_pay_sign (
   const struct TALER_MerchantPrivateKeyP *merch_priv,
   struct GNUNET_CRYPTO_EddsaSignature *merch_sig);
 
+
 /**
  * Verify payment confirmation signature.
  *
@@ -4841,7 +4916,8 @@ TALER_exchange_offline_extension_config_hash_verify (
   const struct TALER_MasterSignatureP *master_sig
   );
 
-/*
+
+/**
  * @brief Representation of an age commitment:  one public key per age group.
  *
  * The number of keys must be be the same as the number of bits set in the
@@ -4850,30 +4926,37 @@ TALER_exchange_offline_extension_config_hash_verify (
 struct TALER_AgeCommitment
 {
 
-  /* The age mask defines the age groups that were a parameter during the
+  /**
-   * generation of this age commitment */
+   * The age mask defines the age groups that were a parameter during the
+   * generation of this age commitment
+   */
   struct TALER_AgeMask mask;
 
-  /* The number of public keys, which must be the same as the number of
+  /**
+   * The number of public keys, which must be the same as the number of
    * groups in the mask.
    */
   size_t num;
 
-  /* The list of #num_pub public keys.  In must have same size as the number of
+  /**
+   * The list of @e num public keys.  In must have same size as the number of
    * age groups defined in the mask.
    *
    * A hash of this list is the hashed commitment that goes into FDC
    * calculation during the withdraw and refresh operations for new coins. That
    * way, the particular age commitment becomes mandatory and bound to a coin.
    *
-   * The list has been allocated via GNUNET_malloc.
+   * The list has been allocated via GNUNET_malloc().
    */
   struct TALER_AgeCommitmentPublicKeyP *keys;
 };
 
+
+// FIXME-oec: document!
 struct TALER_AgeProof
 {
-  /* The number of private keys, which must be at most num_pub_keys.  One minus
+  /**
+   * The number of private keys, which must be at most num_pub_keys.  One minus
    * this number corresponds to the largest age group that is supported with
    * this age commitment.
    * **Note**, that this and the next field are only relevant on the wallet
@@ -4881,7 +4964,8 @@ struct TALER_AgeProof
    */
   size_t num;
 
-  /* List of #num_priv private keys.
+  /**
+   * List of @e num private keys.
    *
    * Note that the list can be _smaller_ than the corresponding list of public
    * keys. In that case, the wallet can sign off only for a subset of the age
@@ -4892,9 +4976,13 @@ struct TALER_AgeProof
   struct TALER_AgeCommitmentPrivateKeyP *keys;
 };
 
+
+// FIXME-oec: document!
 struct TALER_AgeCommitmentProof
 {
+  // FIXME-oec: document!
   struct TALER_AgeCommitment commitment;
+  // FIXME-oec: document!
   struct TALER_AgeProof proof;
 };
 
@@ -4917,7 +5005,7 @@ TALER_age_commitment_hash (
  * @param mask The age mask the defines the age groups
  * @param age The actual age for which an age commitment is generated
  * @param seed The seed that goes into the key generation.  MUST be choosen uniformly random.
- * @param comm_proof[out] The generated age commitment, ->priv and ->pub allocated via GNUNET_malloc on success
+ * @param[out] comm_proof The generated age commitment, ->priv and ->pub allocated via GNUNET_malloc() on success
  * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
  */
 enum GNUNET_GenericReturnValue
@@ -4933,7 +5021,7 @@ TALER_age_restriction_commit (
  *
  * @param orig Original age commitment
  * @param salt Salt to randomly move the points on the elliptic curve in order to generate another, equivalent commitment.
- * @param[out] derived The resulting age commitment, ->priv and ->pub allocated via GNUNET_malloc on success.
+ * @param[out] derived The resulting age commitment, ->priv and ->pub allocated via GNUNET_malloc() on success.
  * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
  */
 enum GNUNET_GenericReturnValue
@@ -4957,10 +5045,11 @@ TALER_age_commitment_attest (
   uint8_t age,
   struct TALER_AgeAttestation *attest);
 
-/*
+
+/**
  * @brief Verify the attestation for an given age and age commitment
  *
- * @param commitent The age commitment that went into the attestation.  Only the public keys are needed.
+ * @param commitment The age commitment that went into the attestation.  Only the public keys are needed.
  * @param age Age (not age group) for which the an attestation should be done
  * @param attest Signature of the age with the appropriate key from the age commitment for the corresponding age group, if applicaple.
  * @return GNUNET_OK when the attestation was successfull, GNUNET_NO no attestation couldn't be verified, GNUNET_SYSERR otherwise
@@ -4971,7 +5060,8 @@ TALER_age_commitment_verify (
   uint8_t age,
   const struct TALER_AgeAttestation *attest);
 
-/*
+
+/**
  * @brief helper function to free memory of a struct TALER_AgeCommitment
  *
  * @param p the commitment from which all memory should be freed.
@@ -4980,7 +5070,8 @@ void
 TALER_age_commitment_free (
   struct TALER_AgeCommitment *p);
 
-/*
+
+/**
  * @brief helper function to free memory of a struct TALER_AgeProof
  *
  * @param p the proof of commitment from which all memory should be freed.
@@ -4989,7 +5080,8 @@ void
 TALER_age_proof_free (
   struct TALER_AgeProof *p);
 
-/*
+
+/**
  * @brief helper function to free memory of a struct TALER_AgeCommitmentProof
  *
  * @param p the commitment and its proof from which all memory should be freed.

src/include/taler_exchange_service.h

@@ -1170,6 +1170,7 @@ struct TALER_EXCHANGE_NonceKey
  * Get a set of CS R values using a /csr-melt request.
  *
  * @param exchange the exchange handle; the exchange must be ready to operate
+ * @param rms master key used for the derivation of the CS values
  * @param nks_len length of the @a nks array
  * @param nks array of denominations and nonces
  * @param res_cb the callback to call when the final result for this request is available
@@ -1263,7 +1264,7 @@ typedef void
  * Get a CS R using a /csr-withdraw request.
  *
  * @param exchange the exchange handle; the exchange must be ready to operate
- * @param dk Which denomination key is the /csr request for
+ * @param pk Which denomination key is the /csr request for
  * @param nonce client nonce for the request
  * @param res_cb the callback to call when the final result for this request is available
  * @param res_cb_cls closure for the above callback
@@ -2377,7 +2378,7 @@ struct TALER_EXCHANGE_MeltResponse
   union
   {
     /**
-     * Results for status #MHD_HTTP_SUCCESS.
+     * Results for status #MHD_HTTP_OK.
      */
     struct
     {
@@ -2512,7 +2513,7 @@ struct TALER_EXCHANGE_RevealResult
   union
   {
     /**
-     * Results for status #MHD_HTTP_SUCCESS.
+     * Results for status #MHD_HTTP_OK.
      */
     struct
     {
@@ -2660,7 +2661,7 @@ struct TALER_EXCHANGE_LinkResult
   union
   {
     /**
-     * Results for status #MHD_HTTP_SUCCESS.
+     * Results for status #MHD_HTTP_OK.
      */
     struct
     {
@@ -2704,7 +2705,7 @@ typedef void
  *
  * @param exchange the exchange handle; the exchange must be ready to operate
  * @param coin_priv private key to request link data for
- * @param age_commitment age commitment to the corresponding coin, might be NULL
+ * @param age_commitment_proof age commitment to the corresponding coin, might be NULL
  * @param link_cb the callback to call with the useful result of the
  *        refresh operation the @a coin_priv was involved in (if any)
  * @param link_cb_cls closure for @a link_cb
@@ -3773,13 +3774,14 @@ TALER_EXCHANGE_management_post_extensions (
   TALER_EXCHANGE_ManagementPostExtensionsCallback cb,
   void *cb_cls);
 
+
 /**
- * Cancel #TALER_EXCHANGE_post_management_extensions() operation.
+ * Cancel #TALER_EXCHANGE_management_post_extensions() operation.
  *
  * @param ph handle of the operation to cancel
  */
 void
-TALER_EXCHANGE_post_management_extensions_cancel (
+TALER_EXCHANGE_management_post_extensions_cancel (
   struct TALER_EXCHANGE_ManagementPostExtensionsHandle *ph);
 
 
@@ -4205,7 +4207,7 @@ TALER_EXCHANGE_management_set_global_fees (
 /**
  * Cancel #TALER_EXCHANGE_management_enable_wire() operation.
  *
- * @param swfh handle of the operation to cancel
+ * @param sgfh handle of the operation to cancel
  */
 void
 TALER_EXCHANGE_management_set_global_fees_cancel (
@@ -4637,7 +4639,7 @@ struct TALER_EXCHANGE_AccountMergeResponse
  * operation.
  *
  * @param cls closure
- * @param pcr HTTP response data
+ * @param amr HTTP response data
  */
 typedef void
 (*TALER_EXCHANGE_AccountMergeCallback) (
@@ -4663,7 +4665,7 @@ struct TALER_EXCHANGE_AccountMergeHandle;
  * @param h_contract_terms hash of the purses' contract
  * @param min_age minimum age of deposits into the purse
  * @param purse_value_after_fees amount that should be in the purse
- * @paran purse_expiration when will the purse expire
+ * @param purse_expiration when will the purse expire
  * @param merge_timestamp when is the merge happening (current time)
  * @param cb function to call with the exchange's result
  * @param cb_cls closure for @a cb
@@ -4758,7 +4760,7 @@ struct TALER_EXCHANGE_PurseCreateMergeHandle;
  * @param contract_terms contract the purse is about
  * @param upload_contract true to upload the contract
  * @param pay_for_purse true to pay for purse creation
- * @paran merge_timestamp when should the merge happen (use current time)
+ * @param merge_timestamp when should the merge happen (use current time)
  * @param cb function to call with the exchange's result
  * @param cb_cls closure for @a cb
  * @return the request handle; NULL upon error

src/include/taler_exchangedb_plugin.h

@@ -2017,6 +2017,16 @@ typedef enum GNUNET_GenericReturnValue
  *
  * @param cls closure
  * @param rowid unique serial ID for the deposit in our DB
+ * @param reserve_pub reserve affected by the merge
+ * @param purse_pub purse being merged
+ * @param h_contract_terms hash over contract of the purse
+ * @param purse_expiration when would the purse expire
+ * @param amount total amount in the purse
+ * @param min_age minimum age of all coins deposited into the purse
+ * @param flags how was the purse created
+ * @param purse_fee if a purse fee was paid, how high is it
+ * @param merge_timestamp when was the merge approved
+ * @param reserve_sig signature by reserve approving the merge
  * @return #GNUNET_OK to continue to iterate, #GNUNET_SYSERR to stop
  */
 typedef enum GNUNET_GenericReturnValue
@@ -2075,6 +2085,10 @@ typedef enum GNUNET_GenericReturnValue
  *
  * @param cls closure
  * @param rowid unique serial ID for the deposit in our DB
+ * @param history_fee fee paid for the request
+ * @param ts timestamp of the request
+ * @param reserve_pub reserve history was requested for
+ * @param reserve_sig signature approving the @a history_fee
  * @return #GNUNET_OK to continue to iterate, #GNUNET_SYSERR to stop
  */
 typedef enum GNUNET_GenericReturnValue
@@ -2108,6 +2122,7 @@ typedef enum GNUNET_GenericReturnValue
  * the goal of auditing the purse refund's execution.
  *
  * @param cls closure
+ * @param rowid row of the refund event
  * @param amount_with_fee amount of the deposit into the purse
  * @param coin_pub coin that is to be refunded the @a given amount_with_fee
  * @param denom_pub denomination of @a coin_pub
@@ -3935,8 +3950,8 @@ struct TALER_EXCHANGEDB_Plugin
    * Insert global fee set into database.
    *
    * @param cls closure
-   * @param start_date when does the fee go into effect
+   * @param start_date when does the fees go into effect
-   * @param end_date when does the fee end being valid
+   * @param end_date when does the fees end being valid
    * @param fees how high is are the global fees
    * @param purse_timeout when do purses time out
    * @param kyc_timeout when do reserves without KYC time out
@@ -5101,7 +5116,7 @@ struct TALER_EXCHANGEDB_Plugin
    * @param[out] in_conflict set to true if @a econtract
    *             conflicts with an existing contract;
    *             in this case, the return value will be
-   *             #GNUNET_DB_STATUS_SUCCESS_ONE despite the failure
+   *             #GNUNET_DB_STATUS_SUCCESS_ONE_RESULT despite the failure
    * @return transaction status code
    */
   enum GNUNET_DB_QueryStatus
@@ -5163,7 +5178,7 @@ struct TALER_EXCHANGEDB_Plugin
    * @param[out] in_conflict set to true if the meta data
    *             conflicts with an existing purse;
    *             in this case, the return value will be
-   *             #GNUNET_DB_STATUS_SUCCESS_ONE despite the failure
+   *             #GNUNET_DB_STATUS_SUCCESS_ONE_RESULT despite the failure
    * @return transaction status code
    */
   enum GNUNET_DB_QueryStatus
@@ -5292,7 +5307,7 @@ struct TALER_EXCHANGEDB_Plugin
    * @param[out] balance_ok set to false if the coin's
    *        remaining balance is below @a amount;
    *             in this case, the return value will be
-   *             #GNUNET_DB_STATUS_SUCCESS_ONE despite the failure
+   *             #GNUNET_DB_STATUS_SUCCESS_ONE_RESULT despite the failure
    * @param[out] conflict the same coin was deposited into
    *        this purse with a different amount already
    * @return transaction status code

src/include/taler_testing_lib.h

@@ -2229,6 +2229,7 @@ TALER_TESTING_cmd_auditor_add_denom_sig (const char *label,
  * @param wire_method wire method to set wire fees for
  * @param wire_fee the wire fee to affirm
  * @param closing_fee the closing fee to affirm
+ * @param wad_fee wad fee to charge
  * @param expected_http_status expected HTTP status from exchange
  * @param bad_sig should we use a bogus signature?
  * @return the command

src/lib/auditor_api_deposit_confirmation.c

@@ -156,6 +156,7 @@ handle_deposit_confirmation_finished (void *cls,
  * @param h_extensions hash over the extensions, if any
  * @param h_contract_terms hash of the contact of the merchant with the customer (further details are never disclosed to the auditor)
  * @param exchange_timestamp timestamp when the deposit was received by the wallet
+ * @param wire_deadline by what time must the amount be wired to the merchant
  * @param refund_deadline date until which the merchant can issue a refund to the customer via the auditor (can be zero if refunds are not allowed); must not be after the @a wire_deadline
  * @param amount_without_fee the amount confirmed to be wired by the exchange to the merchant
  * @param coin_pub coin’s public key

src/lib/exchange_api_batch_withdraw.c

@@ -145,7 +145,8 @@ struct TALER_EXCHANGE_BatchWithdrawHandle
  *
  * @param cls the `struct TALER_EXCHANGE_BatchWithdrawHandle`
  * @param hr HTTP response data
- * @param blind_sig blind signature over the coin, NULL on error
+ * @param blind_sigs array of blind signatures over the coins, NULL on error
+ * @param blind_sigs_length length of the @a blind_sigs array
  */
 static void
 handle_reserve_batch_withdraw_finished (

src/lib/exchange_api_common.h

@@ -50,6 +50,7 @@ TALER_EXCHANGE_check_purse_create_conflict_ (
  *        not match the signature from the proof)
  * @param merge_pub the public key (must match
  *        the signature from the proof)
+ * @param purse_pub the public key of the purse
  * @param exchange_url the base URL of this exchange
  * @param proof the proof to check
  * @return #GNUNET_OK if the @a proof is OK for @a purse_pub and @a merge_pub and conflicts with @a cmerge_sig
@@ -93,7 +94,6 @@ TALER_EXCHANGE_check_purse_coin_conflict_ (
  * @param ccontract_sig conflicting signature (must
  *        not match the signature from the proof)
  * @param purse_pub public key of the purse
- * @param exchange_url the base URL of this exchange
  * @param proof the proof to check
  * @return #GNUNET_OK if the @a proof is OK for @a purse_pub and conflicts with @a ccontract_sig
  */

src/lib/exchange_api_deposits_get.c

@@ -323,7 +323,6 @@ TALER_EXCHANGE_deposits_get (
   TALER_merchant_deposit_sign (h_contract_terms,
                                h_wire,
                                coin_pub,
-                               &merchant,
                                merchant_priv,
                                &merchant_sig);
   {

src/lib/exchange_api_management_post_extensions.c

@@ -118,7 +118,7 @@ handle_post_extensions_finished (void *cls,
             &hr);
     ph->cb = NULL;
   }
-  TALER_EXCHANGE_post_management_extensions_cancel (ph);
+  TALER_EXCHANGE_management_post_extensions_cancel (ph);
 }
 
 
@@ -180,7 +180,7 @@ TALER_EXCHANGE_management_post_extensions (
                                   ph);
   if (NULL == ph->job)
   {
-    TALER_EXCHANGE_post_management_extensions_cancel (ph);
+    TALER_EXCHANGE_management_post_extensions_cancel (ph);
     return NULL;
   }
   return ph;
@@ -188,7 +188,7 @@ TALER_EXCHANGE_management_post_extensions (
 
 
 void
-TALER_EXCHANGE_post_management_extensions_cancel (
+TALER_EXCHANGE_management_post_extensions_cancel (
   struct TALER_EXCHANGE_ManagementPostExtensionsHandle *ph)
 {
   if (NULL != ph->job)

src/lib/exchange_api_melt.c

@@ -417,6 +417,7 @@ start_melt (struct TALER_EXCHANGE_MeltHandle *mh)
  * the application and cancel the operation.
  *
  * @param[in] mh melt request that failed
+ * @param ec error code to fail with
  */
 static void
 fail_mh (struct TALER_EXCHANGE_MeltHandle *mh,

src/testing/testing_api_cmd_refresh.c

@@ -348,15 +348,7 @@ do_reveal_retry (void *cls)
  * coming from the exchange, namely the fresh coins.
  *
  * @param cls closure, a `struct RefreshRevealState`
- * @param hr HTTP response details
+ * @param rr HTTP response details
- * @param num_coins number of fresh coins created, length of the
- *        @a sigs and @a coin_privs arrays, 0 if the operation
- *        failed.
- * @param coin_privs array of @a num_coins private keys for the
- *        coins that were created, NULL on error.
- * @param psa array of @a num_coins planchet secrets (derived from the transfer secret) for each of the coins
- * @param sigs array of signature over @a num_coins coins,
- *        NULL on error.
  */
 static void
 reveal_cb (void *cls,
@@ -594,16 +586,7 @@ do_link_retry (void *cls)
  * withdrawn by the "refresh reveal" CMD.
  *
  * @param cls closure.
- * @param hr HTTP response details
+ * @param lr HTTP response details
- * @param num_coins number of fresh coins created, length of the
- *        @a sigs and @a coin_privs arrays, 0 if the operation
- *        failed.
- * @param coin_privs array of @a num_coins private keys for the
- *        coins that were created, NULL on error.
- * @param sigs array of signature over @a num_coins coins, NULL on
- *        error.
- * @param pubs array of public keys for the @a sigs,
- *        NULL on error.
  */
 static void
 link_cb (void *cls,

src/testing/testing_api_cmd_reserve_history.c

@@ -17,7 +17,7 @@
   <http://www.gnu.org/licenses/>
 */
 /**
- * @file testing/testing_api_cmd_history.c
+ * @file testing/testing_api_cmd_reserve_history.c
  * @brief Implement the /reserve/history test command.
  * @author Marcello Stanisci
  */

src/testing/testing_api_cmd_reserve_status.c

@@ -17,7 +17,7 @@
   <http://www.gnu.org/licenses/>
 */
 /**
- * @file testing/testing_api_cmd_status.c
+ * @file testing/testing_api_cmd_reserve_status.c
  * @brief Implement the /reserve/$RID/status test command.
  * @author Marcello Stanisci
  */

src/util/merchant_signatures.c

@@ -46,12 +46,6 @@ struct TALER_DepositTrackPS
    */
   struct TALER_MerchantWireHashP h_wire GNUNET_PACKED;
 
-  /**
-   * The Merchant's public key.  The deposit inquiry request is to be
-   * signed by the corresponding private key (using EdDSA).
-   */
-  struct TALER_MerchantPublicKeyP merchant;
-
   /**
    * The coin's public key.  This is the value that must have been
    * signed (blindly) by the Exchange.
@@ -68,7 +62,6 @@ TALER_merchant_deposit_sign (
   const struct TALER_PrivateContractHashP *h_contract_terms,
   const struct TALER_MerchantWireHashP *h_wire,
   const struct TALER_CoinSpendPublicKeyP *coin_pub,
-  const struct TALER_MerchantPublicKeyP *merchant_pub,
   const struct TALER_MerchantPrivateKeyP *merchant_priv,
   struct TALER_MerchantSignatureP *merchant_sig)
 {
@@ -77,9 +70,9 @@ TALER_merchant_deposit_sign (
     .purpose.size = htonl (sizeof (dtp)),
     .h_contract_terms = *h_contract_terms,
     .h_wire = *h_wire,
-    .merchant = *merchant_pub,
     .coin_pub = *coin_pub
   };
+
   GNUNET_CRYPTO_eddsa_sign (&merchant_priv->eddsa_priv,
                             &dtp,
                             &merchant_sig->eddsa_sig);
@@ -97,7 +90,6 @@ TALER_merchant_deposit_verify (
   struct TALER_DepositTrackPS tps = {
     .purpose.size = htonl (sizeof (tps)),
     .purpose.purpose = htonl (TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION),
-    .merchant = *merchant,
     .coin_pub = *coin_pub,
     .h_contract_terms = *h_contract_terms,
     .h_wire = *h_wire
@@ -107,7 +99,7 @@ TALER_merchant_deposit_verify (
     GNUNET_CRYPTO_eddsa_verify (TALER_SIGNATURE_MERCHANT_TRACK_TRANSACTION,
                                 &tps,
                                 &merchant_sig->eddsa_sig,
-                                &tps.merchant.eddsa_pub);
+                                &merchant->eddsa_pub);
 }