[GNUnet-SVN] [taler-twister] 02/04: Commenting the "testing API"

[gnunet]

This is an automated email from the git hooks/post-receive script.

marcello pushed a commit to branch master
in repository twister.

commit 3f3f5d875ae78698a874540e184a8cf49837ecce
Author: Marcello Stanisci <address@hidden>
AuthorDate: Tue May 29 17:16:36 2018 +0200

    Commenting the "testing API"
---
 src/twister/testing_api_cmd_exec_client.c | 233 ++++++++++++++++++++----------
 1 file changed, 156 insertions(+), 77 deletions(-)

diff --git a/src/twister/testing_api_cmd_exec_client.c 
b/src/twister/testing_api_cmd_exec_client.c
index 60973b2..b62b501 100644
--- a/src/twister/testing_api_cmd_exec_client.c
+++ b/src/twister/testing_api_cmd_exec_client.c
@@ -29,6 +29,10 @@
 #include <taler/taler_testing_lib.h>
 #include "taler_twister_testing_lib.h"
 
+
+/**
+ * State for a "modify object" CMD.
+ */
 struct ModifyObjectState
 {
   /**
@@ -41,16 +45,22 @@ struct ModifyObjectState
    */
   const char *path;
 
+
+  /**
+   * Value to substitute to the original one.
+   */
   const char *value;
 
   /**
    * Config file name to pass to the CLI client.
    */
   const char *config_filename;
-
 };
 
 
+/**
+ * State for a "flip object" CMD.
+ */
 struct FlipObjectState
 {
   /**
@@ -59,7 +69,7 @@ struct FlipObjectState
   struct GNUNET_OS_Process *proc;
 
   /**
-   * Object-like notation to the object to delete.
+   * Object-like notation to the string-object to flip.
    */
   const char *path;
 
@@ -69,6 +79,10 @@ struct FlipObjectState
   const char *config_filename;
 };
 
+
+/**
+ * State for a "delete object" CMD.
+ */
 struct DeleteObjectState
 {
   /**
@@ -87,6 +101,10 @@ struct DeleteObjectState
   const char *config_filename;
 };
 
+
+/**
+ * State for a "malform request" CMD.
+ */
 struct MalformRequestState
 {
   /**
@@ -100,6 +118,10 @@ struct MalformRequestState
   const char *config_filename;
 };
 
+
+/**
+ * State for a "malform response" CMD.
+ */
 struct MalformResponseState
 {
   /**
@@ -113,6 +135,10 @@ struct MalformResponseState
   const char *config_filename;
 };
 
+
+/**
+ * State for a "hack response code" CMD.
+ */
 struct HackResponseCodeState
 {
   /**
@@ -121,8 +147,7 @@ struct HackResponseCodeState
   struct GNUNET_OS_Process *proc;
 
   /**
-   * HTTP status code the twister will return upon its next
-   * connection.
+   * HTTP status code to substitute to the original one.
    */
   unsigned int http_status;
 
@@ -134,10 +159,11 @@ struct HackResponseCodeState
 
 
 /**
- * Clean up after the command.  Run during forced termination
- * (CTRL-C) or test failure or test success.
+ * Free the state from a "hack response code" CMD, and
+ * possibly kill its process if it did not terminate yet.
  *
- * @param cls closure
+ * @param cls closure.
+ * @param cmd the command being cleaned up.
  */
 static void
 hack_response_code_cleanup
@@ -158,15 +184,13 @@ hack_response_code_cleanup
 }
 
 /**
- * Extract information from a command that is useful for other
- * commands.
+ * Offer data internal to a "hack response code" CMD,
+ * to other commands.
  *
  * @param cls closure
  * @param ret[out] result (could be anything)
  * @param trait name of the trait
- * @param selector more detailed information about which object
- *                 to return in case there were multiple generated
- *                 by the command
+ * @param index index number of the object to offer.
  * @return #GNUNET_OK on success
  */
 static int
@@ -188,6 +212,14 @@ hack_response_code_traits (void *cls,
                                   index);
 }
 
+
+/**
+ * Run a "hack response code" CMD.
+ *
+ * @param cls closure.
+ * @param cmd the command being run.
+ * @param is the interpreter state.
+ */
 static void
 hack_response_code_run (void *cls,
                         const struct TALER_TESTING_Command *cmd,
@@ -220,13 +252,13 @@ hack_response_code_run (void *cls,
 
 
 /**
- * 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 config_filename configuration filename.
  * @param http_status new response code to use
- *
  * @return the command
  */
 struct TALER_TESTING_Command
@@ -251,10 +283,11 @@ TALER_TESTING_cmd_hack_response_code (const char *label,
 }
 
 /**
- * Clean up after the command.  Run during forced termination
- * (CTRL-C) or test failure or test success.
+ * Free the state from a "delete object" CMD, and
+ * possibly kill its process if it did not terminate yet.
  *
- * @param cls closure
+ * @param cls closure.
+ * @param cmd the command being cleaned up.
  */
 static void
 delete_object_cleanup
@@ -275,15 +308,13 @@ delete_object_cleanup
 }
 
 /**
- * Extract information from a command that is useful for other
- * commands.
+ * Offer data internal to a "delete object" CMD,
+ * to other commands.
  *
  * @param cls closure
  * @param ret[out] result (could be anything)
  * @param trait name of the trait
- * @param selector more detailed information about which object
- *                 to return in case there were multiple generated
- *                 by the command
+ * @param index index number of the object to offer.
  * @return #GNUNET_OK on success
  */
 static int
@@ -306,7 +337,11 @@ delete_object_traits (void *cls,
 }
 
 /**
- * FIXME: document.
+ * Run a "delete object" CMD.
+ *
+ * @param cls closure.
+ * @param cmd the command being run.
+ * @param is the interpreter state.
  */
 static void
 delete_object_run (void *cls,
@@ -333,7 +368,11 @@ delete_object_run (void *cls,
 }
 
 /**
- * TODO.
+ * Free the state from a "modify object" CMD, and
+ * possibly kill its process if it did not terminate yet.
+ *
+ * @param cls closure.
+ * @param cmd the command being cleaned up.
  */
 static void
 modify_object_cleanup
@@ -353,17 +392,14 @@ modify_object_cleanup
   GNUNET_free (mos);
 }
 
-
 /**
- * Extract information from a command that is useful for other
- * commands.
+ * Offer data internal to a "modify object" CMD,
+ * to other commands.
  *
  * @param cls closure
  * @param ret[out] result (could be anything)
  * @param trait name of the trait
- * @param selector more detailed information about which object
- *                 to return in case there were multiple generated
- *                 by the command
+ * @param index index number of the object to offer.
  * @return #GNUNET_OK on success
  */
 static int
@@ -385,9 +421,12 @@ modify_object_traits (void *cls,
                                   index);
 }
 
-
 /**
- * FIXME: document.
+ * Run a "modify object" CMD.  The "download fashion" of it.
+ *
+ * @param cls closure.
+ * @param cmd the command being run.
+ * @param is the interpreter state.
  */
 static void
 modify_object_dl_run (void *cls,
@@ -414,6 +453,14 @@ modify_object_dl_run (void *cls,
   TALER_TESTING_wait_for_sigchld (is);
 }
 
+
+/**
+ * Run a "modify object" CMD, the "upload fashion" of it.
+ *
+ * @param cls closure.
+ * @param cmd the command being run.
+ * @param is the interpreter state.
+ */
 static void
 modify_object_ul_run (void *cls,
                       const struct TALER_TESTING_Command *cmd,
@@ -440,13 +487,13 @@ modify_object_ul_run (void *cls,
 }
 
 /**
- * This command deletes the JSON object 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 delete.
- *
  * @return the command
  */
 struct TALER_TESTING_Command
@@ -471,13 +518,12 @@ TALER_TESTING_cmd_delete_object (const char *label,
 }
 
 
-//////
-
 /**
- * Clean up after the command.  Run during forced termination
- * (CTRL-C) or test failure or test success.
+ * Free the state from a "flip object" CMD, and
+ * possibly kill its process if it did not terminate yet.
  *
- * @param cls closure
+ * @param cls closure.
+ * @param cmd the command being cleaned up.
  */
 static void
 flip_object_cleanup
@@ -498,15 +544,13 @@ flip_object_cleanup
 }
 
 /**
- * Extract information from a command that is useful for other
- * commands.
+ * Offer data internal to a "flip object" CMD,
+ * to other commands.
  *
  * @param cls closure
  * @param ret[out] result (could be anything)
  * @param trait name of the trait
- * @param selector more detailed information about which object
- *                 to return in case there were multiple generated
- *                 by the command
+ * @param index index number of the object to offer.
  * @return #GNUNET_OK on success
  */
 static int
@@ -529,7 +573,11 @@ flip_object_traits (void *cls,
 }
 
 /**
- * FIXME: document.
+ * Run a "flip object" CMD, the upload fashion of it.
+ *
+ * @param cls closure.
+ * @param cmd the command being run.
+ * @param is the interpreter state.
  */
 static void
 flip_upload_run (void *cls,
@@ -556,9 +604,12 @@ flip_upload_run (void *cls,
 }
 
 
-
 /**
- * FIXME: document.
+ * Run a "flip object" CMD, the download fashion of it.
+ *
+ * @param cls closure.
+ * @param cmd the command being run.
+ * @param is the interpreter state.
  */
 static void
 flip_download_run (void *cls,
@@ -584,14 +635,14 @@ flip_download_run (void *cls,
   TALER_TESTING_wait_for_sigchld (is);
 }
 
+
 /**
- * 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
@@ -617,13 +668,12 @@ TALER_TESTING_cmd_flip_upload (const char *label,
 
 
 /**
- * This command deletes the JSON object pointed by @a 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 delete.
- *
+ *        to flip.
  * @return the command
  */
 struct TALER_TESTING_Command
@@ -649,8 +699,13 @@ TALER_TESTING_cmd_flip_download (const char *label,
 
 
 /**
- * TODO.
+ * Free the state from a "malform request" CMD, and
+ * possibly kill its process if it did not terminate yet.
+ *
+ * @param cls closure.
+ * @param cmd the command being cleaned up.
  */
+
 static void
 malform_request_cleanup
   (void *cls,
@@ -671,15 +726,13 @@ malform_request_cleanup
 
 
 /**
- * Extract information from a command that is useful for other
- * commands.
+ * Offer data internal to a "malform request" CMD,
+ * to other commands.
  *
  * @param cls closure
  * @param ret[out] result (could be anything)
  * @param trait name of the trait
- * @param selector more detailed information about which object
- *                 to return in case there were multiple generated
- *                 by the command
+ * @param index index number of the object to offer.
  * @return #GNUNET_OK on success
  */
 static int
@@ -701,9 +754,12 @@ malform_request_traits (void *cls,
                                   index);
 }
 
-
 /**
- * FIXME: document.
+ * Run a "malform request" CMD.
+ *
+ * @param cls closure.
+ * @param cmd the command being run.
+ * @param is the interpreter state.
  */
 static void
 malform_request_run (void *cls,
@@ -729,9 +785,12 @@ malform_request_run (void *cls,
   TALER_TESTING_wait_for_sigchld (is);
 }
 
-
 /**
- * TODO.
+ * Free the state from a "malform response" CMD, and
+ * possibly kill its process if it did not terminate yet.
+ *
+ * @param cls closure.
+ * @param cmd the command being cleaned up.
  */
 static void
 malform_response_cleanup
@@ -752,16 +811,15 @@ malform_response_cleanup
 }
 
 
+
 /**
- * Extract information from a command that is useful for other
- * commands.
+ * Offer data internal to a "malform response" CMD,
+ * to other commands.
  *
  * @param cls closure
  * @param ret[out] result (could be anything)
  * @param trait name of the trait
- * @param selector more detailed information about which object
- *                 to return in case there were multiple generated
- *                 by the command
+ * @param index index number of the object to offer.
  * @return #GNUNET_OK on success
  */
 static int
@@ -785,7 +843,11 @@ malform_response_traits (void *cls,
 
 
 /**
- * FIXME: document.
+ * Run a "malform response" CMD.
+ *
+ * @param cls closure.
+ * @param cmd the command being run.
+ * @param is the interpreter state.
  */
 static void
 malform_response_run (void *cls,
@@ -812,12 +874,11 @@ malform_response_run (void *cls,
 }
 
 /**
- * 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
@@ -840,8 +901,8 @@ TALER_TESTING_cmd_malform_request (const char *label,
 }
 
 /**
- * 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.
@@ -869,12 +930,15 @@ TALER_TESTING_cmd_malform_response (const char *label,
 }
 
 /**
- * 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
  */
@@ -901,6 +965,19 @@ TALER_TESTING_cmd_modify_object_dl (const char *label,
   return cmd;
 }
 
+
+/**
+ * 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,
@@ -924,3 +1001,5 @@ TALER_TESTING_cmd_modify_object_ul (const char *label,
   return cmd;
 }
 
+
+/* end of testing_api_cmd_exec_client.c */

-- 
To stop receiving notification emails like this one, please contact
address@hidden