twister

commit 747ef703b46af9be76cd22da99b2cc1f83f17194
parent 7fb2c7c349b57e019ee356b7888fe8b9e4793398
Author: Marcello Stanisci <stanisci.m@gmail.com>
Date:   Tue, 29 May 2018 16:26:20 +0200

Fixing comments from the "twister API".

Diffstat:
M
src/twister/twister_api.c
 | 
81
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------------

1 file changed, 68 insertions(+), 13 deletions(-)
diff --git a/src/twister/twister_api.c b/src/twister/twister_api.c
@@ -40,13 +40,30 @@
  */
 struct TALER_TWISTER_Operation
 {
+
+  /**
+   * Pointer to next operation.
+   */
   struct TALER_TWISTER_Operation *next;
+
+  /**
+   * Pointer to previous operation.
+   */
   struct TALER_TWISTER_Operation *prev;
 
+  /**
+   * Pointer to main handle (= connection to the twister).
+   */
   struct TALER_TWISTER_Handle *h;
 
+  /**
+   * Callback for this operation.
+   */
   GNUNET_SCHEDULER_TaskCallback cb;
 
+  /**
+   * Closure to pass the callback above.
+   */
   void *cb_cls;
 };
 
@@ -66,10 +83,15 @@ struct TALER_TWISTER_Handle
    */
   struct GNUNET_MQ_Handle *mq;
 
+  /**
+   * First pending operation.
+   */
   struct TALER_TWISTER_Operation *op_head;
 
+  /**
+   * Last pending operation.
+   */
   struct TALER_TWISTER_Operation *op_tail;
-
 };
 
 
@@ -90,7 +112,8 @@ mq_error_handler (void *cls,
 
   GNUNET_MQ_destroy (h->mq);
   h->mq = NULL;
-  GNUNET_assert (0); /* FIXME: maybe give test case nicer way to shut down... */
+  /* FIXME: maybe give test case nicer way to shut down... */
+  GNUNET_assert (0);
 }
 
 
@@ -191,9 +214,10 @@ TALER_TWISTER_disconnect (struct TALER_TWISTER_Handle *h)
 /**
  * Abort operation.  Twister behavior may then include the
  * changes requested by the operation, or not!  Must be called
- * before the operations callback was invoked.
+ * before the operation 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)
@@ -207,7 +231,8 @@ TALER_TWISTER_cancel (struct TALER_TWISTER_Operation *op)
  * 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)
  */
@@ -243,7 +268,8 @@ TALER_TWISTER_malform_upload
  * 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)
  */
@@ -276,13 +302,15 @@ TALER_TWISTER_malform
 
 
 /**
- * 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)
  */
@@ -314,6 +342,20 @@ TALER_TWISTER_flip_download
   return op;
 }
 
+
+/**
+ * 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 has batched this
+ *        request
+ * @param cb_cls closure for @a cb
+ * @return operation handle (to possibly abort)
+ */
 struct TALER_TWISTER_Operation *
 TALER_TWISTER_flip_upload
   (struct TALER_TWISTER_Handle *h,
@@ -347,7 +389,8 @@ TALER_TWISTER_flip_upload
 }
 
 /**
- * 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
@@ -390,9 +433,8 @@ TALER_TWISTER_delete_path
  * @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
  *
@@ -427,6 +469,19 @@ TALER_TWISTER_modify_path_dl (struct TALER_TWISTER_Handle *h,
   return op;
 }
 
+
+/**
+ * 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,