Commenting the "testing API" header file

1 files changed, 43 insertions, 24 deletions

diff --git a/src/include/taler_twister_testing_lib.h b/src/include/taler_twister_testing_lib.h
index 6605eac..f35efe1 100644
--- a/src/include/taler_twister_testing_lib.h
+++ b/src/include/taler_twister_testing_lib.h
@@ -32,46 +32,43 @@
   do {GNUNET_break (0); return NULL; } while (0)
 
 /**
- * Command that replaces the HTTP response code for
- * the next connection that will be made to the twister.
+ * Define a "hack response code" CMD.  This causes the next
+ * response code (from the service proxied by the twister) to
+ * be substituted with @a http_status.
  *
  * @param label command label
- * @param http_status new response code to use
  * @param config_filename configuration filename.
- *
+ * @param http_status new response code to use
  * @return the command
  */
 struct TALER_TESTING_Command
 TALER_TESTING_cmd_hack_response_code (const char *label,
                                       const char *config_filename,
                                       unsigned int http_status);
-
-
 /**
- * This command deletes the JSON object contained in the
- * response and pointed by @a path.
+ * Create a "delete object" CMD.  This command deletes
+ * the JSON object pointed by @a path.
  *
  * @param label command label
  * @param config_filename configuration filename.
  * @param path object-like path notation to point the object
- *        to be made empty.  "f1.0.f2" will empty the object
- *        {"f1": [{"f2": "I'll be deleted"}]}.
- *
+ *        to delete.
  * @return the command
  */
 struct TALER_TESTING_Command
 TALER_TESTING_cmd_delete_object (const char *label,
                                  const char *config_filename,
                                  const char *path);
-
-
 /**
- * This command deletes the JSON object pointed by @a path.
+ * Create a "modify object" CMD.  This command instructs
+ * the twister to modify the next object that is downloaded
+ * from the proxied service.
  *
  * @param label command label
  * @param config_filename configuration filename.
  * @param path object-like path notation to point the object
- *        to delete.
+ *        to modify.
+ * @param value value to put as the object's.
  *
  * @return the command
  */
@@ -80,14 +77,29 @@ TALER_TESTING_cmd_modify_object_dl (const char *label,
                                     const char *config_filename,
                                     const char *path,
                                     const char *value);
+
+/**
+ * Create a "modify object" CMD.  This command instructs
+ * the twister to modify the next object that will be uploaded
+ * to the proxied service.
+ *
+ * @param label command label
+ * @param config_filename configuration filename.
+ * @param path object-like path notation pointing the object
+ *        to modify.
+ * @param value value to put as the object's.
+ * @return the command
+ */
 struct TALER_TESTING_Command
 TALER_TESTING_cmd_modify_object_ul (const char *label,
                                     const char *config_filename,
                                     const char *path,
                                     const char *value);
+
+
 /**
- * This command makes the next response randomly malformed
- * (by truncating it).
+ * Create a "malform response" CMD.  This command makes
+ * the next response randomly malformed (by truncating it).
  *
  * @param label command label
  * @param config_filename configuration filename.
@@ -99,26 +111,23 @@ TALER_TESTING_cmd_malform_response (const char *label,
                                     const char *config_filename);
 
 /**
- * This command makes the next request randomly malformed
- * (by truncating it).
+ * Create a "malform request" CMD.  This command makes the
+ * next request randomly malformed (by truncating it).
  *
  * @param label command label
  * @param config_filename configuration filename.
- *
  * @return the command
  */
 struct TALER_TESTING_Command
 TALER_TESTING_cmd_malform_request (const char *label,
                                    const char *config_filename);
-
 /**
- * This command deletes the JSON object pointed by @a path.
+ * Define a "flip object" command, for objects to upload.
  *
  * @param label command label
  * @param config_filename configuration filename.
  * @param path object-like path notation to point the object
- *        to delete.
- *
+ *        to flip.
  * @return the command
  */
 struct TALER_TESTING_Command
@@ -126,6 +135,16 @@ TALER_TESTING_cmd_flip_upload (const char *label,
                                const char *config_filename,
                                const char *path);
 
+
+/**
+ * Define a "flip object" command, for objects to download.
+ *
+ * @param label command label
+ * @param config_filename configuration filename.
+ * @param path object-like path notation to point the object
+ *        to flip.
+ * @return the command
+ */
 struct TALER_TESTING_Command
 TALER_TESTING_cmd_flip_download (const char *label,
                                  const char *config_filename,