[GNUnet-SVN] [taler-twister] 03/04: Commenting the "twister API" header file

[gnunet]

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

marcello pushed a commit to branch master
in repository twister.

commit ca9ecfd24ad7dba6d529fc8acb2fc8e9edcbd247
Author: Marcello Stanisci <address@hidden>
AuthorDate: Tue May 29 17:26:35 2018 +0200

    Commenting the "twister API" header file
---
 src/include/taler_twister_service.h | 82 ++++++++++++++++++++++---------------
 src/twister/twister_api.c           | 39 +++++++++---------
 2 files changed, 68 insertions(+), 53 deletions(-)

diff --git a/src/include/taler_twister_service.h 
b/src/include/taler_twister_service.h
index 2672865..a2b963c 100644
--- a/src/include/taler_twister_service.h
+++ b/src/include/taler_twister_service.h
@@ -1,22 +1,21 @@
 /*
-      This file is part of Taler
-      Copyright (C) 2018 Taler Systems SA
+  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,
-      write to the Free Software Foundation, Inc., 51 Franklin
-      Street, Fifth Floor, Boston, MA 02110-1301, USA.
- */
+  You should have received a copy of the GNU General Public
+  License along with Taler; see the file COPYING.  If not,
+  write to the Free Software Foundation, Inc., 51 Franklin
+  Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
 #ifndef TALER_TWISTER_SERVICE_H_
 #define TALER_TWISTER_SERVICE_H_
@@ -80,9 +79,8 @@ struct TALER_TWISTER_Operation;
  * @a modify_value.
  *
  * @param h twister instance to control
- * @param modify_path object-like notation path to the object to
- *        modify
- * @param modify_value value to use for @a modify_path
+ * @param path object-like notation path to the object to modify
+ * @param value value to use for @a modify_path
  * @param cb callback to call once twister gets this instruction.
  * @param cb_cls closure for @a cb_callback
  *
@@ -95,6 +93,19 @@ TALER_TWISTER_modify_path_dl (struct TALER_TWISTER_Handle *h,
                               GNUNET_SCHEDULER_TaskCallback cb,
                               void *cb_cls);
 
+
+/**
+ * Change the JSON field pointed by @a path to the new @a value.
+ * It only applies to upload objects.
+ *
+ * @param h twister instance to control
+ * @param path object-like notation path to the object to modify
+ * @param value value to use for @a modify_path
+ * @param cb callback to call once twister gets this instruction.
+ * @param cb_cls closure for @a cb_callback
+ *
+ * @return operation handle.
+ */
 struct TALER_TWISTER_Operation *
 TALER_TWISTER_modify_path_ul (struct TALER_TWISTER_Handle *h,
                               const char *path,
@@ -102,13 +113,15 @@ TALER_TWISTER_modify_path_ul (struct TALER_TWISTER_Handle 
*h,
                               GNUNET_SCHEDULER_TaskCallback cb,
                               void *cb_cls);
 /**
- * Randomly flip a character into the JSON string
- * object pointed to by @a path.
+ * Instruct the twister to flip a character into
+ * the string JSON field that belongs to the object
+ * being returned to the HTTP client.
  *
  * @param h twister instance to control
  * @param path object-like notation to point the string
  *        object where we seek a character to flip.
- * @param cb function to call once twister is ready
+ * @param cb function to call once twister has processed this
+ *        request
  * @param cb_cls closure for @a cb
  * @return operation handle (to possibly abort)
  */
@@ -120,13 +133,15 @@ TALER_TWISTER_flip_download
    void *cb_cls);
 
 /**
- * Randomly flip a character into the JSON string
- * object pointed to by @a path.
+ * Instruct the twister to flip a character into
+ * the string JSON field that belongs to the object
+ * being uploaded to the proxied service.
  *
  * @param h twister instance to control
  * @param path object-like notation to point the string
  *        object where we seek a character to flip.
- * @param cb function to call once twister is ready
+ * @param cb function to call once twister has batched this
+ *        request
  * @param cb_cls closure for @a cb
  * @return operation handle (to possibly abort)
  */
@@ -157,7 +172,8 @@ TALER_TWISTER_change_response_code
  * Randomly truncate the response.
  *
  * @param h twister instance to control
- * @param cb function to call once twister is ready
+ * @param cb function to call once twister has processed this
+ *           request.
  * @param cb_cls closure for @a cb
  * @return operation handle (to possibly abort)
  */
@@ -171,7 +187,8 @@ TALER_TWISTER_malform
  * Randomly truncate the request.
  *
  * @param h twister instance to control
- * @param cb function to call once twister is ready
+ * @param cb function to call once twister is ready; tipically
+ *        a acknowledge function.
  * @param cb_cls closure for @a cb
  * @return operation handle (to possibly abort)
  */
@@ -182,7 +199,8 @@ TALER_TWISTER_malform_upload
    void *cb_cls);
 
 /**
- * Delete the object pointed to by @a path.
+ * Delete the object pointed to by @a path.  Note, this
+ * object belongs to the JSON response object.
  *
  * @param h twister instance to control
  * @param path object-like notation to point the object to be
@@ -204,8 +222,8 @@ TALER_TWISTER_delete_path
  * changes requested by the operation, or not!  Must be called
  * before the operations callback was invoked.
  *
- * @param op operation to cancel, operation's callback will not
- *        be called
+ * @param op operation to cancel,
+ *        operation's callback will not be called
  */
 void
 TALER_TWISTER_cancel (struct TALER_TWISTER_Operation *op);
@@ -221,11 +239,10 @@ TALER_TWISTER_cancel (struct TALER_TWISTER_Operation *op);
 /** @} */ /* end of group nse */
 
 /**
- * Prepare execution of twister service:
- * mainly check if port is available
+ * Prepare twister for execution; mainly checks whether the
+ * HTTP port is available and construct the base URL based on it.
  *
  * @param config_filename configuration file name.
- *
  * @return twister base URL, NULL upon errors.
  */
 char *
@@ -235,7 +252,6 @@ TALER_TESTING_prepare_twister (const char *config_filename);
  * Run the twister service.
  *
  * @param config_filename configuration file name.
- *
  * @return twister process handle, NULL upon errors.
  */
 struct GNUNET_OS_Process *
diff --git a/src/twister/twister_api.c b/src/twister/twister_api.c
index b5e332e..182ee7f 100644
--- a/src/twister/twister_api.c
+++ b/src/twister/twister_api.c
@@ -1,23 +1,22 @@
 /*
-     This file is part of Taler.
-     Copyright (C) 2009, 2010, 2011, 2016 GNUnet e.V.
-     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 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,
-     write to the Free Software Foundation, Inc., 51 Franklin
-     Street, Fifth Floor, Boston, MA 02110-1301, USA.
-*/
+  This file is part of Taler.
+  Copyright (C) 2009, 2010, 2011, 2016 GNUnet e.V.
+  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 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,
+  write to the Free Software Foundation, Inc., 51 Franklin
+  Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
 
 /**
  * @file twister_api.c
@@ -146,7 +145,7 @@ handle_acknowledgement (void *cls,
  * Connect to the twister service.
  *
  * @param cfg the configuration to use
- * @return handle to use
+ * @return handle to use in #TALER_TWISTER_disconnect to disconnect
  */
 struct TALER_TWISTER_Handle *
 TALER_TWISTER_connect

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