Commenting the remaining "lib" traits.

11 files changed, 233 insertions, 156 deletions

diff --git a/src/bank-lib/testing_api_cmd_history.c b/src/bank-lib/testing_api_cmd_history.c
index ccd29e1c6..d062446d5 100644
--- a/src/bank-lib/testing_api_cmd_history.c
+++ b/src/bank-lib/testing_api_cmd_history.c
@@ -125,7 +125,7 @@ test_cancelled (struct TALER_TESTING_Interpreter *is,
 
     /* XXX: Errors reported here are NOT fatal */
 
-    /* Rejected wire transfers have hold a reference to a
+    /* Rejected wire transfers have a non-NULL reference to a
      * reject command to mark them as rejected. So errors
      * about "reject traits" not found are NOT fatal here */
     if (GNUNET_OK != TALER_TESTING_get_trait_rejected
diff --git a/src/exchange-lib/testing_api_trait_amount.c b/src/exchange-lib/testing_api_trait_amount.c
index f21ec8704..9c37783b5 100644
--- a/src/exchange-lib/testing_api_trait_amount.c
+++ b/src/exchange-lib/testing_api_trait_amount.c
@@ -19,7 +19,7 @@
 
 /**
  * @file exchange-lib/testing_api_trait_amount.c
- * @brief offer amounts as traits
+ * @brief offer amounts as traits.
  * @author Marcello Stanisci
  */
 
@@ -35,10 +35,11 @@
 /**
  * Obtain an amount from a @a cmd.
  *
- * @param cmd command to extract trait from
- * @param selector which amount to pick if @a cmd has multiple
+ * @param cmd command to extract the amount from.
+ * @param index which amount to pick if @a cmd has multiple
  *        on offer
- * @param amount[out] set to the amount
+ * @param amount[out] set to the amount.
+ *
  * @return #GNUNET_OK on success
  */
 int
@@ -53,6 +54,16 @@ TALER_TESTING_get_trait_amount_obj (
                       index);
 }
 
+
+/**
+ * Offer amount.
+ *
+ * @param index which amount to offer, in case there are
+ *        multiple available.
+ * @param amount the amount to offer.
+ *
+ * @return the trait.
+ */
 struct TALER_TESTING_Trait
 TALER_TESTING_make_trait_amount_obj (
   unsigned int index,
diff --git a/src/exchange-lib/testing_api_trait_blinding_key.c b/src/exchange-lib/testing_api_trait_blinding_key.c
index 23eb7acc1..12ce12ae1 100644
--- a/src/exchange-lib/testing_api_trait_blinding_key.c
+++ b/src/exchange-lib/testing_api_trait_blinding_key.c
@@ -18,7 +18,7 @@
 */
 /**
  * @file exchange-lib/testing_api_trait_blinding_key.c
- * @brief main interpreter loop for testcases
+ * @brief offer blinding keys as traits.
  * @author Christian Grothoff
  * @author Marcello Stanisci
  */
@@ -36,15 +36,16 @@
  * Obtain a blinding key from a @a cmd.
  *
  * @param cmd command to extract trait from
- * @param selector which coin to pick if @a cmd has multiple on offer
- * @param blinding_key[out] set to the blinding key of the coin
- * @return #GNUNET_OK on success
+ * @param index which coin to pick if @a cmd has multiple on offer.
+ * @param blinding_key[out] set to the offered blinding key.
+ *
+ * @return #GNUNET_OK on success.
  */
 int
-TALER_TESTING_get_trait_blinding_key (
-  const struct TALER_TESTING_Command *cmd,
-  unsigned int index,
-  struct TALER_DenominationBlindingKeyP **blinding_key)
+TALER_TESTING_get_trait_blinding_key
+  (const struct TALER_TESTING_Command *cmd,
+   unsigned int index,
+   struct TALER_DenominationBlindingKeyP **blinding_key)
 {
   return cmd->traits (cmd->cls,
                       (void **) blinding_key,
@@ -53,10 +54,19 @@ TALER_TESTING_get_trait_blinding_key (
 }
 
 
+
+/**
+ * Offer blinding key.
+ *
+ * @param index index number to associate to the offered key.
+ * @param blinding_key blinding key to offer.
+ *
+ * @return the trait.
+ */
 struct TALER_TESTING_Trait
-TALER_TESTING_make_trait_blinding_key (
-  unsigned int index,
-  const struct TALER_DenominationBlindingKeyP *blinding_key)
+TALER_TESTING_make_trait_blinding_key
+  (unsigned int index,
+   const struct TALER_DenominationBlindingKeyP *blinding_key)
 {
   struct TALER_TESTING_Trait ret = {
     .index = index,
@@ -67,5 +77,4 @@ TALER_TESTING_make_trait_blinding_key (
   return ret;
 }
 
-
 /* end of testing_api_trait_blinding_key.c */
diff --git a/src/exchange-lib/testing_api_trait_coin_priv.c b/src/exchange-lib/testing_api_trait_coin_priv.c
index 522f72859..5e9193f1f 100644
--- a/src/exchange-lib/testing_api_trait_coin_priv.c
+++ b/src/exchange-lib/testing_api_trait_coin_priv.c
@@ -19,7 +19,7 @@
 
 /**
  * @file exchange-lib/testing_api_trait_coin_priv.c
- * @brief main interpreter loop for testcases
+ * @brief coin priv traits.
  * @author Christian Grothoff
  * @author Marcello Stanisci
  */
@@ -36,11 +36,11 @@
 /**
  * Obtain a coin private key from a @a cmd.
  *
- * @param cmd command to extract trait from
- * @param selector which coin to pick if @a cmd has multiple on
- *        offer
- * @param coin_priv[out] set to the private key of the coin
- * @return #GNUNET_OK on success
+ * @param cmd command to extract trait from.
+ * @param index index of the coin priv to obtain.
+ * @param coin_priv[out] set to the private key of the coin.
+ *
+ * @return #GNUNET_OK on success.
  */
 int
 TALER_TESTING_get_trait_coin_priv
@@ -55,6 +55,15 @@ TALER_TESTING_get_trait_coin_priv
 }
 
 
+
+/**
+ * Offer coin private key.
+ *
+ * @param index index number to associate with offered coin priv.
+ * @param coin_priv coin private key to offer.
+ *
+ * @return the trait.
+ */
 struct TALER_TESTING_Trait
 TALER_TESTING_make_trait_coin_priv
   (unsigned int index,
@@ -69,5 +78,4 @@ TALER_TESTING_make_trait_coin_priv
   return ret;
 }
 
-
 /* end of testing_api_trait_coin_priv.c */
diff --git a/src/exchange-lib/testing_api_trait_denom_pub.c b/src/exchange-lib/testing_api_trait_denom_pub.c
index 92c003ce3..8caaf69fb 100644
--- a/src/exchange-lib/testing_api_trait_denom_pub.c
+++ b/src/exchange-lib/testing_api_trait_denom_pub.c
@@ -18,7 +18,7 @@
 */
 /**
  * @file exchange-lib/testing_api_trait_denom_pub.c
- * @brief main interpreter loop for testcases
+ * @brief denom pub traits.
  * @author Christian Grothoff
  * @author Marcello Stanisci
  */
@@ -36,10 +36,10 @@
  * Obtain a denomination public key from a @a cmd.
  *
  * @param cmd command to extract trait from
- * @param selector which coin to pick if @a cmd has multiple on
- *        offer
- * @param denom_pub[out] set to the blinding key of the coin
- * @return #GNUNET_OK on success
+ * @param index index number of the denom to obtain.
+ * @param denom_pub[out] set to the offered denom pub.
+ *
+ * @return #GNUNET_OK on success.
  */
 int
 TALER_TESTING_get_trait_denom_pub
@@ -57,10 +57,10 @@ TALER_TESTING_get_trait_denom_pub
 /**
  * Make a trait for a denomination public key.
  *
- * @param selector in case the trait provides multiple
- *        objects, this parameter extracts a particular one.
- * @param denom_pub pointer to the data to be returned from
- *        this trait
+ * @param index index number to associate to the offered denom pub.
+ * @param denom_pub denom pub to offer with this trait.
+ *
+ * @return the trait.
  */
 struct TALER_TESTING_Trait
 TALER_TESTING_make_trait_denom_pub
diff --git a/src/exchange-lib/testing_api_trait_denom_sig.c b/src/exchange-lib/testing_api_trait_denom_sig.c
index e50a3ba8a..5d7d708e8 100644
--- a/src/exchange-lib/testing_api_trait_denom_sig.c
+++ b/src/exchange-lib/testing_api_trait_denom_sig.c
@@ -36,17 +36,17 @@
 /**
  * Obtain a denomination signature from a @a cmd.
  *
- * @param cmd command to extract trait from
- * @param selector which signature to pick if @a cmd has multiple
- *        on offer
- * @param denom_sig[out] set to the signature
- * @return #GNUNET_OK on success
+ * @param cmd command to extract the denom sig from.
+ * @param index index number associated with the denom sig.
+ * @param denom_sig[out] set to the offered signature.
+ *
+ * @return #GNUNET_OK on success.
  */
 int
-TALER_TESTING_get_trait_denom_sig (
-  const struct TALER_TESTING_Command *cmd,
-  unsigned int index,
-  struct TALER_DenominationSignature **denom_sig)
+TALER_TESTING_get_trait_denom_sig
+  (const struct TALER_TESTING_Command *cmd,
+   unsigned int index,
+   struct TALER_DenominationSignature **denom_sig)
 {
   return cmd->traits (cmd->cls,
                       (void **) denom_sig,
@@ -55,10 +55,20 @@ TALER_TESTING_get_trait_denom_sig (
 }
 
 
+
+/**
+ * Offer denom sig.
+ *
+ * @param index index number to associate to the signature on
+ *        offer.
+ * @param denom_sig the denom sig on offer.
+ *
+ * @return the trait.
+ */
 struct TALER_TESTING_Trait
-TALER_TESTING_make_trait_denom_sig (
-  unsigned int index,
-  const struct TALER_DenominationSignature *denom_sig)
+TALER_TESTING_make_trait_denom_sig
+  (unsigned int index,
+   const struct TALER_DenominationSignature *denom_sig)
 {
   struct TALER_TESTING_Trait ret = {
     .index = index,
diff --git a/src/exchange-lib/testing_api_trait_json.c b/src/exchange-lib/testing_api_trait_json.c
index 40dddbfa3..675be6cf5 100644
--- a/src/exchange-lib/testing_api_trait_json.c
+++ b/src/exchange-lib/testing_api_trait_json.c
@@ -34,11 +34,13 @@
 /**
  * Obtain wire details from @a cmd.
  *
- * @param cmd command to extract trait from
- * @param index always (?) zero, as one command sticks
- *        to one bank account
+ * @param cmd command to extract the wire details from.
+ * @param index index number associate with the wire details
+ *        on offer; usually zero, as one command sticks to
+ *        one bank account.
  * @param wire_details[out] where to write the wire details.
- * @return #GNUNET_OK on success
+ *
+ * @return #GNUNET_OK on success.
  */
 int
 TALER_TESTING_get_trait_wire_details
@@ -55,10 +57,12 @@ TALER_TESTING_get_trait_wire_details
 /**
  * Offer wire details in a trait.
  *
- * @param index always (?) zero, as one command sticks
- *        to one bank account
- * @param wire_details wire details to offer
- * @return the trait, to be put in the traits array of the command
+ * @param index index number associate with the wire details
+ *        on offer; usually zero, as one command sticks to
+ *        one bank account.
+ * @param wire_details wire details to offer.
+ *
+ * @return the trait.
  */
 struct TALER_TESTING_Trait
 TALER_TESTING_make_trait_wire_details
diff --git a/src/exchange-lib/testing_api_trait_number.c b/src/exchange-lib/testing_api_trait_number.c
index 4db887927..67b01ae8e 100644
--- a/src/exchange-lib/testing_api_trait_number.c
+++ b/src/exchange-lib/testing_api_trait_number.c
@@ -33,13 +33,13 @@
 #define TALER_TESTING_TRAIT_UINT64 "uint-64"
 
 /**
- * Obtain a "number" value from @a cmd.
+ * Obtain a number from @a cmd.
  *
- * @param cmd command to extract trait from
- * @param selector which coin to pick if @a cmd has multiple on
- * offer
+ * @param cmd command to extract the number from.
+ * @param index the number's index number.
  * @param n[out] set to the number coming from @a cmd.
- * @return #GNUNET_OK on success
+ *
+ * @return #GNUNET_OK on success.
  */
 int
 TALER_TESTING_get_trait_uint
@@ -53,11 +53,15 @@ TALER_TESTING_get_trait_uint
                       index);
 }
 
+
+
 /**
- * @param selector associate the object with this "tag"
- * @param n which object should be returned
+ * Offer a number.
+ *
+ * @param index the number's index number.
+ * @param n the number to offer.
  *
- * @return the trait, to be put in the traits array of the command
+ * @return #GNUNET_OK on success.
  */
 struct TALER_TESTING_Trait
 TALER_TESTING_make_trait_uint
@@ -73,13 +77,13 @@ TALER_TESTING_make_trait_uint
 }
 
 /**
- * Obtain a "number" value from @a cmd.
+ * Obtain a "number" value from @a cmd, 64-bit version.
  *
- * @param cmd command to extract trait from
- * @param selector which coin to pick if @a cmd has multiple on
- * offer
+ * @param cmd command to extract the number from.
+ * @param index the number's index number.
  * @param n[out] set to the number coming from @a cmd.
- * @return #GNUNET_OK on success
+ *
+ * @return #GNUNET_OK on success.
  */
 int
 TALER_TESTING_get_trait_uint64
@@ -94,10 +98,10 @@ TALER_TESTING_get_trait_uint64
 }
 
 /**
- * @param selector associate the object with this "tag"
- * @param n which object should be returned
+ * Offer number trait, 64-bit version.
  *
- * @return the trait, to be put in the traits array of the command
+ * @param index the number's index number.
+ * @param n number to offer.
  */
 struct TALER_TESTING_Trait
 TALER_TESTING_make_trait_uint64
@@ -112,6 +116,4 @@ TALER_TESTING_make_trait_uint64
   return ret;
 }
 
-
-
 /* end of testing_api_trait_number.c */
diff --git a/src/exchange-lib/testing_api_trait_process.c b/src/exchange-lib/testing_api_trait_process.c
index e3c1bdf4e..297b5d39c 100644
--- a/src/exchange-lib/testing_api_trait_process.c
+++ b/src/exchange-lib/testing_api_trait_process.c
@@ -2,21 +2,24 @@
   This file is part of TALER
   Copyright (C) 2018 Taler Systems SA
 
-  TALER is free software; you can redistribute it and/or modify it under the
-  terms of the GNU General Public License as published by the Free Software
-  Foundation; either version 3, or (at your option) any later version.
+  TALER is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as
+  published by the Free Software Foundation; either version 3,
+  or (at your option) any later version.
 
-  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
-  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
-  A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+  TALER is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty
+  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the GNU General Public License for more details.
 
-  You should have received a copy of the GNU General Public License along with
-  TALER; see the file COPYING.  If not, see
+  You should have received a copy of the GNU General Public
+  License along with TALER; see the file COPYING.  If not, see
   <http://www.gnu.org/licenses/>
 */
+
 /**
  * @file exchange-lib/testing_api_trait_process.c
- * @brief trait for a command that launches a process
+ * @brief trait offering process handles.
  * @author Christian Grothoff
  * @author Marcello Stanisci
  */
@@ -31,17 +34,21 @@
 
 
 /**
- * Obtain location where a command stores a pointer to a process
+ * Obtain location where a command stores a pointer to a process.
+ *
+ * @param cmd command to extract trait from.
+ * @param index which process to pick if @a cmd
+ *        has multiple on offer.
+ * @param coin_priv[out] set to the address of the pointer to the
+ *        process.
  *
- * @param cmd command to extract trait from
- * @param selector which process to pick if @a cmd has multiple on offer
- * @param coin_priv[out] set to address of the pointer to the process
- * @return #GNUNET_OK on success
+ * @return #GNUNET_OK on success.
  */
 int
-TALER_TESTING_get_trait_process (const struct TALER_TESTING_Command *cmd,
-                                 unsigned int index,
-                                 struct GNUNET_OS_Process ***processp)
+TALER_TESTING_get_trait_process
+  (const struct TALER_TESTING_Command *cmd,
+   unsigned int index,
+   struct GNUNET_OS_Process ***processp)
 {
   return cmd->traits (cmd->cls,
                       (void **) processp,
@@ -50,9 +57,19 @@ TALER_TESTING_get_trait_process (const struct TALER_TESTING_Command *cmd,
 }
 
 
+/**
+ * Offer location where a command stores a pointer to a process.
+ * 
+ * @param index offered location index number, in case there are
+ *        multiple on offer.
+ * @param processp process location to offer.
+ *
+ * @return the trait.
+ */
 struct TALER_TESTING_Trait
-TALER_TESTING_make_trait_process (unsigned int index,
-                                  struct GNUNET_OS_Process **processp)
+TALER_TESTING_make_trait_process
+  (unsigned int index,
+   struct GNUNET_OS_Process **processp)
 {
   struct TALER_TESTING_Trait ret = {
     .index = index,
@@ -63,5 +80,4 @@ TALER_TESTING_make_trait_process (unsigned int index,
   return ret;
 }
 
-
 /* end of testing_api_trait_process.c */
diff --git a/src/exchange-lib/testing_api_trait_reserve_priv.c b/src/exchange-lib/testing_api_trait_reserve_priv.c
index 971741f65..587a11c6a 100644
--- a/src/exchange-lib/testing_api_trait_reserve_priv.c
+++ b/src/exchange-lib/testing_api_trait_reserve_priv.c
@@ -35,17 +35,17 @@
 /**
  * Obtain a reserve private key from a @a cmd.
  *
- * @param cmd command to extract trait from
- * @param selector which coin to pick if @a cmd has multiple on
- *        offer
- * @param reserve_priv[out] set to the private key of the reserve
- * @return #GNUNET_OK on success
+ * @param cmd command to extract the reserve priv from.
+ * @param index reserve priv's index number.
+ * @param reserve_priv[out] set to the reserve priv.
+ *
+ * @return #GNUNET_OK on success.
  */
 int
-TALER_TESTING_get_trait_reserve_priv (
-  const struct TALER_TESTING_Command *cmd,
-  unsigned int index,
-  struct TALER_ReservePrivateKeyP **reserve_priv)
+TALER_TESTING_get_trait_reserve_priv
+  (const struct TALER_TESTING_Command *cmd,
+   unsigned int index,
+   struct TALER_ReservePrivateKeyP **reserve_priv)
 {
   return cmd->traits (cmd->cls,
                       (void **) reserve_priv,
@@ -54,10 +54,19 @@ TALER_TESTING_get_trait_reserve_priv (
 }
 
 
+
+/**
+ * Offer a reserve private key.
+ *
+ * @param index reserve priv's index number.
+ * @param reserve_priv reserve private key to offer.
+ *
+ * @return the trait.
+ */
 struct TALER_TESTING_Trait
-TALER_TESTING_make_trait_reserve_priv (
-  unsigned int index,
-  const struct TALER_ReservePrivateKeyP *reserve_priv)
+TALER_TESTING_make_trait_reserve_priv
+  (unsigned int index,
+   const struct TALER_ReservePrivateKeyP *reserve_priv)
 {
   struct TALER_TESTING_Trait ret = {
     .index = index,
@@ -67,5 +76,4 @@ TALER_TESTING_make_trait_reserve_priv (
   return ret;
 }
 
-
 /* end of testing_api_trait_reserve_priv.c */
diff --git a/src/exchange-lib/testing_api_trait_string.c b/src/exchange-lib/testing_api_trait_string.c
index fb5af93e5..e04398e67 100644
--- a/src/exchange-lib/testing_api_trait_string.c
+++ b/src/exchange-lib/testing_api_trait_string.c
@@ -19,8 +19,7 @@
 
 /**
  * @file exchange-lib/testing_api_trait_string.c
- * @brief offers strings traits.  Mostly used to offer
- *        stringified JSONs.
+ * @brief offers strings traits.
  * @author Marcello Stanisci
  */
 #include "platform.h"
@@ -40,12 +39,12 @@
 /**
  * Obtain contract terms from @a cmd.
  *
- * @param cmd command to extract trait from
- * @param index always (?) zero, as one command sticks
- *        to one bank account
+ * @param cmd command to extract the contract terms from.
+ * @param index contract terms index number.
  * @param contract_terms[out] where to write the contract
  *        terms.
- * @return #GNUNET_OK on success
+ *
+ * @return #GNUNET_OK on success.
  */
 int
 TALER_TESTING_get_trait_contract_terms
@@ -60,10 +59,12 @@ TALER_TESTING_get_trait_contract_terms
 }
 
 /**
- * @param index always (?) zero, as one command sticks
- *        to one bank account
- * @param contract_terms contract terms to offer
- * @return the trait, to be put in the traits array of the command
+ * Offer contract terms.
+ *
+ * @param index contract terms index number.
+ * @param contract_terms contract terms to offer.
+ * 
+ * @return the trait.
  */
 struct TALER_TESTING_Trait
 TALER_TESTING_make_trait_contract_terms
@@ -82,11 +83,13 @@ TALER_TESTING_make_trait_contract_terms
 /**
  * Obtain a transfer subject from @a cmd.
  *
- * @param cmd command to extract trait from
- * @param index always (?) zero, as one command sticks
- *        to one bank transfer
- * @param transfer_subject[out] where to write the wire details.
- * @return #GNUNET_OK on success
+ * @param cmd command to extract the subject from.
+ * @param index index number associated with the transfer
+ *        subject to offer.
+ * @param transfer_subject[out] where to write the offered
+ *        transfer subject.
+ *
+ * @return #GNUNET_OK on success.
  */
 int
 TALER_TESTING_get_trait_transfer_subject
@@ -101,12 +104,13 @@ TALER_TESTING_get_trait_transfer_subject
 }
 
 /**
- * Offer wire details in a trait.
+ * Offer transfer subject.
  *
- * @param index always (?) zero, as one command sticks
- *        to one bank account
- * @param wire_details wire details to offer
- * @return the trait, to be put in the traits array of the command
+ * @param index index number associated with the transfer
+ *        subject being offered.
+ * @param transfer_subject transfer subject to offer.
+ *
+ * @return the trait.
  */
 struct TALER_TESTING_Trait
 TALER_TESTING_make_trait_transfer_subject
@@ -125,11 +129,12 @@ TALER_TESTING_make_trait_transfer_subject
 /**
  * Obtain an amount from @a cmd.
  *
- * @param cmd command to extract trait from
+ * @param cmd command to extract the amount from.
  * @param index which amount is to be picked, in case
  *        multiple are offered.
  * @param amount[out] where to write the wire details.
- * @return #GNUNET_OK on success
+ *
+ * @return #GNUNET_OK on success.
  */
 int
 TALER_TESTING_get_trait_amount
@@ -146,10 +151,11 @@ TALER_TESTING_get_trait_amount
 /**
  * Offer amount in a trait.
  *
- * @param index which amount is to be picked, in case
- *        multiple are offered.
- * @param amount the amount to offer
- * @return the trait, to be put in the traits array of the command
+ * @param index which amount is to be offered,
+ *        in case multiple are offered.
+ * @param amount the amount to offer.
+ *
+ * @return the trait.
  */
 struct TALER_TESTING_Trait
 TALER_TESTING_make_trait_amount
@@ -168,11 +174,12 @@ TALER_TESTING_make_trait_amount
 /**
  * Obtain a url from @a cmd.
  *
- * @param cmd command to extract trait from
+ * @param cmd command to extract the url from.
  * @param index which url is to be picked, in case
  *        multiple are offered.
- * @param amount[out] where to write the url.
- * @return #GNUNET_OK on success
+ * @param url[out] where to write the url.
+ *
+ * @return #GNUNET_OK on success.
  */
 int
 TALER_TESTING_get_trait_url
@@ -189,10 +196,11 @@ TALER_TESTING_get_trait_url
 /**
  * Offer url in a trait.
  *
- * @param index which url is to be picked, in case
- *        multiple are offered.
- * @param url the url to offer
- * @return the trait, to be put in the traits array of the command
+ * @param index which url is to be picked,
+ *        in case multiple are offered.
+ * @param url the url to offer.
+ *
+ * @return the trait.
  */
 struct TALER_TESTING_Trait
 TALER_TESTING_make_trait_url
@@ -211,11 +219,12 @@ TALER_TESTING_make_trait_url
 /**
  * Obtain a order id from @a cmd.
  *
- * @param cmd command to extract trait from
+ * @param cmd command to extract the order id from.
  * @param index which order id is to be picked, in case
  *        multiple are offered.
  * @param order_id[out] where to write the order id.
- * @return #GNUNET_OK on success
+ *
+ * @return #GNUNET_OK on success.
  */
 int
 TALER_TESTING_get_trait_order_id
@@ -232,10 +241,11 @@ TALER_TESTING_get_trait_order_id
 /**
  * Offer order id in a trait.
  *
- * @param index which order id is to be picked, in case
- *        multiple are offered.
- * @param order_id the url to offer
- * @return the trait, to be put in the traits array of the command
+ * @param index which order id is to be offered,
+ *        in case multiple are offered.
+ * @param order_id the order id to offer.
+ *
+ * @return the trait.
  */
 struct TALER_TESTING_Trait
 TALER_TESTING_make_trait_order_id
@@ -251,14 +261,15 @@ TALER_TESTING_make_trait_order_id
 }
 
 /**
- * Obtain the reference from a bank transfer which has
- * been rejected.
+ * Obtain the reference to a "reject" CMD.  Usually offered
+ * by _rejected_ bank transfers.
  *
- * @param cmd command to extract trait from
+ * @param cmd command to extract the reference from.
  * @param index which reference is to be picked, in case
  *        multiple are offered.
- * @param rejected_reference[out] where to write the order id.
- * @return #GNUNET_OK on success
+ * @param rejected_reference[out] where to write the reference.
+ *
+ * @return #GNUNET_OK on success.
  */
 int
 TALER_TESTING_get_trait_rejected
@@ -273,13 +284,13 @@ TALER_TESTING_get_trait_rejected
 }
 
 /**
- * Offer reference to a bank transfer which has been
- * rejected.
+ * Offer a "reject" CMD reference.
  *
- * @param index which reference is to be picked, in case
- *        multiple are offered.
- * @param rejected_reference the url to offer
- * @return the trait, to be put in the traits array of the command
+ * @param index which reference is to be offered,
+ *        in case multiple are offered.
+ * @param rejected_reference the reference to offer.
+ *
+ * @return the trait.
  */
 struct TALER_TESTING_Trait
 TALER_TESTING_make_trait_rejected
@@ -294,6 +305,4 @@ TALER_TESTING_make_trait_rejected
   return ret;
 }
 
-
-
 /* end of testing_api_trait_string.c */