[GNUnet-SVN] r34785 - gnunet/src/include

[gnunet]

Author: ch3
Date: 2014-12-24 16:11:38 +0100 (Wed, 24 Dec 2014)
New Revision: 34785

Modified:
   gnunet/src/include/gnunet_rps_service.h
Log:
Added documenting comments

Modified: gnunet/src/include/gnunet_rps_service.h
===================================================================
--- gnunet/src/include/gnunet_rps_service.h     2014-12-24 15:03:58 UTC (rev 
34784)
+++ gnunet/src/include/gnunet_rps_service.h     2014-12-24 15:11:38 UTC (rev 
34785)
@@ -39,13 +39,36 @@
  */
 #define GNUNET_RPS_VERSION 0x00000000
 
+/**
+ * Handle for the random peer sampling service
+ */
+struct GNUNET_RPS_Handle;
+
+/**
+ * Handle for one request to the rps service
+ */
+struct GNUNET_RPS_Request_Handle;
+
+/**
+ * Callback called when requested random peers are available.
+ *
+ * @param cls the closure given with the request
+ * @param num_peers the number of peers returned
+ * @param peers array with num_peers PeerIDs
+ */
 typedef void (* GNUNET_RPS_NotifyReadyCB) (void *cls, uint64_t num_peers, 
struct GNUNET_PeerIdentity *peers);
 
 /**
  * Request n random peers.
  *
- * This is a wrapper function that makes it useless to have to
+ * This is a wrapper function that makes it unnecessary to have to
  * (dis)connect from/to the service.
+ * 
+ * @param cfg the configuration to use
+ * @param n number of peers to be returned
+ * @param ready_cb the callback to be called when the PeerIDs are available
+ * @param cls closure given to the callback
+ * @return handle to this request
  */
   struct GNUNET_RPS_Request_Handle *
 GNUNET_RPS_request_peers_single_call (const struct GNUNET_CONFIGURATION_Handle 
*cfg,
@@ -55,6 +78,9 @@
 
 /**
  * Connect to the rps service
+ *
+ * @param cfg configuration to use
+ * @return handle to the rps service
  */
   struct GNUNET_RPS_Handle *
 GNUNET_RPS_connect( const struct GNUNET_CONFIGURATION_Handle *cfg );
@@ -66,6 +92,12 @@
  * but needs a GNUNET_RPS_Handle.
  * This exists only for other parts of GNUnet that expect having to
  * (dis)connect from/to a service.
+ *
+ * @param h handle to the rps service
+ * @param n number of random peers to return
+ * @param ready_cb the callback to be called when the peers are available
+ * @param cls a closure that will be given to the callback
+ * @return handle to this request
  */
   struct GNUNET_RPS_Request_Handle *
 GNUNET_RPS_request_peers (struct GNUNET_RPS_Handle *h, uint64_t n,
@@ -74,12 +106,16 @@
 
 /**
  * Cancle an issued request.
+ *
+ * @param rh handle of the pending request to be canceled
  */
   void
 GNUNET_RPS_request_cancel ( struct GNUNET_RPS_Request_Handle *rh );
 
 /**
  * Disconnect from the rps service
+ *
+ * @param h the handle to the rps service
  */
   void
 GNUNET_RPS_disconnect ( struct GNUNET_RPS_Handle *h );