[GNUnet-SVN] r30180 - in gnunet/src: include scalarproduct

[gnunet]

Author: cfuchs
Date: 2013-10-14 15:00:11 +0200 (Mon, 14 Oct 2013)
New Revision: 30180

Modified:
   gnunet/src/include/gnunet_scalarproduct_service.h
   gnunet/src/scalarproduct/gnunet-service-scalarproduct.c
   gnunet/src/scalarproduct/scalarproduct.h
   gnunet/src/scalarproduct/scalarproduct_api.c
Log:
more work on doxygenization for SP



Modified: gnunet/src/include/gnunet_scalarproduct_service.h
===================================================================
--- gnunet/src/include/gnunet_scalarproduct_service.h   2013-10-14 12:35:46 UTC 
(rev 30179)
+++ gnunet/src/include/gnunet_scalarproduct_service.h   2013-10-14 13:00:11 UTC 
(rev 30180)
@@ -49,12 +49,11 @@
   GNUNET_SCALARPRODUCT_Status_ServiceDisconnected
 };
 
+/**
+ * Opaque declaration of the SP-Handle
+ */
 struct GNUNET_SCALARPRODUCT_Handle;
 
-typedef void (*GNUNET_SCALARPRODUCT_ResponseMessageHandler) (void *cls,
-                                                             const struct 
GNUNET_MessageHeader *msg,
-                                                             enum 
GNUNET_SCALARPRODUCT_ResponseStatus status);
-
 /**
  * Continuation called to notify client about result of the
  * operation.
@@ -69,7 +68,7 @@
  *
  * @param cls closure
  * @param status Status of the request
- * @param type result of the computation
+ * @param result result of the computation
  */
 typedef void (*GNUNET_SCALARPRODUCT_DatumProcessor) (void *cls,
                                                      enum 
GNUNET_SCALARPRODUCT_ResponseStatus status,
@@ -78,8 +77,8 @@
 /**
  * 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
@@ -102,8 +101,8 @@
 /**
  * Used by Bob's client to cooperate with Alice,
  *
- * @param h handle to our configuration
- * @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
@@ -120,7 +119,7 @@
  * Cancel an ongoing computation or revoke our collaboration offer.
  * Closes the connection to the service
  *
- * @param h handel to terminate
+ * @param h computation handle to terminate
  */
 void
 GNUNET_SCALARPRODUCT_cancel (struct GNUNET_SCALARPRODUCT_ComputationHandle * 
h);
@@ -128,7 +127,6 @@
 /**
  * Cancel ALL ongoing computation or revoke our collaboration offer.
  * Closes ALL connections to the service
- *
  */
 void
 GNUNET_SCALARPRODUCT_disconnect ();

Modified: gnunet/src/scalarproduct/gnunet-service-scalarproduct.c
===================================================================
--- gnunet/src/scalarproduct/gnunet-service-scalarproduct.c     2013-10-14 
12:35:46 UTC (rev 30179)
+++ gnunet/src/scalarproduct/gnunet-service-scalarproduct.c     2013-10-14 
13:00:11 UTC (rev 30180)
@@ -384,7 +384,7 @@
   my_lambda = gcry_mpi_new (0);
 
   // calculate lambda
-  // lambda = \frac{(p-1)*(q-1)}{gcd(p-1,q-1)}
+  // lambda = frac{(p-1)*(q-1)}{gcd(p-1,q-1)}
   gcry_mpi_sub_ui (tmp1, p, 1);
   gcry_mpi_sub_ui (tmp2, q, 1);
   gcry_mpi_gcd (gcd, tmp1, tmp2);
@@ -1149,10 +1149,10 @@
 /**
  * executed by bob:
  * compute the values
- *  (1)[]: $E_A(a_{\pi(i)}) \otimes E_A(- r_{\pi(i)} - b_{\pi(i)}) &= 
E_A(a_{\pi(i)} - r_{\pi(i)} - b_{\pi(i)})$
- *  (2)[]: $E_A(a_{\pi'(i)}) \otimes E_A(- r_{\pi'(i)}) &= E_A(a_{\pi'(i)} - 
r_{\pi'(i)})$
- *      S: $S := E_A(\sum (r_i + b_i)^2)$
- *     S': $S' := E_A(\sum r_i^2)$
+ *  (1)[]: $E_A(a_{pi(i)}) otimes E_A(- r_{pi(i)} - b_{pi(i)}) &= 
E_A(a_{pi(i)} - r_{pi(i)} - b_{pi(i)})$
+ *  (2)[]: $E_A(a_{pi'(i)}) otimes E_A(- r_{pi'(i)}) &= E_A(a_{pi'(i)} - 
r_{pi'(i)})$
+ *      S: $S := E_A(sum (r_i + b_i)^2)$
+ *     S': $S' := E_A(sum r_i^2)$
  *
  * @param request the requesting session + bob's requesting peer
  * @param response the responding session + bob's client handle

Modified: gnunet/src/scalarproduct/scalarproduct.h
===================================================================
--- gnunet/src/scalarproduct/scalarproduct.h    2013-10-14 12:35:46 UTC (rev 
30179)
+++ gnunet/src/scalarproduct/scalarproduct.h    2013-10-14 13:00:11 UTC (rev 
30180)
@@ -52,7 +52,7 @@
  * Maximum count of elements we can put into a multipart message
  */
 #define MULTIPART_ELEMENT_CAPACITY ((GNUNET_SERVER_MAX_MESSAGE_SIZE - 1 - 
sizeof (struct GNUNET_SCALARPRODUCT_multipart_message)) / 
PAILLIER_ELEMENT_LENGTH)
-    
+
 /**
  * Log an error message at log-level 'level' that indicates
  * a failure of the command 'cmd' with the message given

Modified: gnunet/src/scalarproduct/scalarproduct_api.c
===================================================================
--- gnunet/src/scalarproduct/scalarproduct_api.c        2013-10-14 12:35:46 UTC 
(rev 30179)
+++ gnunet/src/scalarproduct/scalarproduct_api.c        2013-10-14 13:00:11 UTC 
(rev 30180)
@@ -95,6 +95,9 @@
    */
   struct GNUNET_SCALARPRODUCT_client_request * msg;
 
+  /**
+   * The msg handler callback
+   */
   union
   {
   /**
@@ -145,11 +148,11 @@
 
 
 /**
- * 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 @@
 
 
 /**
- * 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 @@
 
 
 /**
- * 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 @@
 
 
 /**
- * Transmits the request to the VectorProduct Sevice
+ * Transmits the request to the VectorProduct Service
  *
  * @param cls Closure
  * @param size Size of the buffer
@@ -309,8 +312,8 @@
 /**
  * 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
@@ -394,8 +397,8 @@
 /**
  * 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
@@ -488,9 +491,10 @@
 
 
 /**
- * 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 +517,7 @@
     }
 }
 /**
- * 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