- debug

[oweals/gnunet.git] / src / scalarproduct / scalarproduct_api.c

diff --git a/src/scalarproduct/scalarproduct_api.c b/src/scalarproduct/scalarproduct_api.c
index 0f8a409cc48a149028c8151f0cdeaa4ffe891766..dcacd85c98152c7ee1f11d21977b4e6738915610 100644 (file)
--- a/src/scalarproduct/scalarproduct_api.c
+++ b/src/scalarproduct/scalarproduct_api.c
@@ -95,6 +95,9 @@ struct GNUNET_SCALARPRODUCT_ComputationHandle
    */
   struct GNUNET_SCALARPRODUCT_client_request * msg;
 
+  /**
+   * The msg handler callback
+   */
   union
   {
   /**
@@ -145,11 +148,11 @@ GNUNET_SCALARPRODUCT_cancel (struct GNUNET_SCALARPRODUCT_ComputationHandle * h);
 
 
 /**
- * Handles the RESULT received in reply of prepare_response from the
- * service
+ * Handles the STATUS received from the service for a response, does not contain a payload
  *
- * @param cls Handle to the Master Context
+ * @param cls our Handle
  * @param msg Pointer to the response received
+ * @param status the condition the request was terminated with (eg: disconnect)
  */
 static void
 process_status_message (void *cls,
@@ -163,11 +166,11 @@ process_status_message (void *cls,
 
 
 /**
- * Handles the RESULT received in reply of prepare_response from the
- * service
+ * Handles the RESULT received from the service for a request, should contain a result MPI value
  *
- * @param cls Handle to the Master Context
+ * @param cls our Handle
  * @param msg Pointer to the response received
+ * @param status the condition the request was terminated with (eg: disconnect)
  */
 static void
 process_result_message (void *cls,
@@ -212,7 +215,7 @@ process_result_message (void *cls,
 
 
 /**
- * Called when a response is received from the service. After basic check
+ * Called when a response is received from the service. After basic check, the
  * handler in qe->response_proc is called. This functions handles the response
  * to the client which used the API.
  *
@@ -255,7 +258,7 @@ receive_cb (void *cls, const struct GNUNET_MessageHeader *msg)
 
 
 /**
- * Transmits the request to the VectorProduct Sevice
+ * Transmits the request to the VectorProduct Service
  *
  * @param cls Closure
  * @param size Size of the buffer
@@ -309,20 +312,22 @@ transmit_request (void *cls, size_t size,
 /**
  * Used by Bob's client to cooperate with Alice,
  *
- * @param h handle to the master context
- * @param key Session key - unique to the requesting client
+ * @param cfg the gnunet configuration handle
+ * @param key Session key unique to the requesting client
  * @param elements Array of elements of the vector
  * @param element_count Number of elements in the vector
  * @param cont Callback function
  * @param cont_cls Closure for the callback function
+ * 
+ * @return a new handle for this computation
  */
 struct GNUNET_SCALARPRODUCT_ComputationHandle *
-GNUNET_SCALARPRODUCT_response (const struct GNUNET_CONFIGURATION_Handle *cfg,
+GNUNET_SCALARPRODUCT_response (const struct GNUNET_CONFIGURATION_Handle * cfg,
                                const struct GNUNET_HashCode * key,
                                const int32_t * elements,
                                uint32_t element_count,
                                GNUNET_SCALARPRODUCT_ContinuationWithStatus cont,
-                               void *cont_cls)
+                               void * cont_cls)
 {
   struct GNUNET_SCALARPRODUCT_ComputationHandle *h;
   struct GNUNET_SCALARPRODUCT_client_request *msg;
@@ -394,8 +399,8 @@ GNUNET_SCALARPRODUCT_response (const struct GNUNET_CONFIGURATION_Handle *cfg,
 /**
  * Request by Alice's client for computing a scalar product
  *
- * @param h handle to the master context
- * @param key Session key - unique to the requesting client
+ * @param cfg the gnunet configuration handle
+ * @param key Session key should be unique to the requesting client
  * @param peer PeerID of the other peer
  * @param elements Array of elements of the vector
  * @param element_count Number of elements in the vector
@@ -403,9 +408,11 @@ GNUNET_SCALARPRODUCT_response (const struct GNUNET_CONFIGURATION_Handle *cfg,
  * @param mask_bytes number of bytes in the mask
  * @param cont Callback function
  * @param cont_cls Closure for the callback function
+ * 
+ * @return a new handle for this computation
  */
 struct GNUNET_SCALARPRODUCT_ComputationHandle *
-GNUNET_SCALARPRODUCT_request (const struct GNUNET_CONFIGURATION_Handle *cfg,
+GNUNET_SCALARPRODUCT_request (const struct GNUNET_CONFIGURATION_Handle * cfg,
                               const struct GNUNET_HashCode * key,
                               const struct GNUNET_PeerIdentity *peer,
                               const int32_t * elements,
@@ -413,7 +420,7 @@ GNUNET_SCALARPRODUCT_request (const struct GNUNET_CONFIGURATION_Handle *cfg,
                               const unsigned char * mask,
                               uint32_t mask_bytes,
                               GNUNET_SCALARPRODUCT_DatumProcessor cont,
-                              void *cont_cls)
+                              void * cont_cls)
 {
   struct GNUNET_SCALARPRODUCT_ComputationHandle *h;
   struct GNUNET_SCALARPRODUCT_client_request *msg;
@@ -488,9 +495,10 @@ GNUNET_SCALARPRODUCT_request (const struct GNUNET_CONFIGURATION_Handle *cfg,
 
 
 /**
- * Disconnect from the scalarproduct service.
+ * Cancel an ongoing computation or revoke our collaboration offer.
+ * Closes the connection to the service
  *
- * @param h a computation handle to cancel
+ * @param h computation handle to terminate
  */
 void
 GNUNET_SCALARPRODUCT_cancel (struct GNUNET_SCALARPRODUCT_ComputationHandle * h)
@@ -513,7 +521,7 @@ GNUNET_SCALARPRODUCT_cancel (struct GNUNET_SCALARPRODUCT_ComputationHandle * h)
     }
 }
 /**
- * Cancel ALL our ongoing scalar product computations and collaboration offers.
+ * Cancel ALL ongoing computation or revoke our collaboration offer.
  * Closes ALL connections to the service
  */
 void
@@ -534,4 +542,4 @@ GNUNET_SCALARPRODUCT_disconnect ()
     }
 }
 
-/* end of ext_api.c */
+/* end of scalarproduct_api.c */