From 23fa03199548424901516bfea8f9568ef492833a Mon Sep 17 00:00:00 2001
From: Julius Bünger <buenger@mytum.de>
Date: Wed, 24 Dec 2014 15:11:38 +0000
Subject: Added documenting comments

---
 src/include/gnunet_rps_service.h | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

(limited to 'src')

diff --git a/src/include/gnunet_rps_service.h b/src/include/gnunet_rps_service.h
index 3a3b2cbad..2b0d136cb 100644
--- a/src/include/gnunet_rps_service.h
+++ b/src/include/gnunet_rps_service.h
@@ -39,13 +39,36 @@ extern "C"
  */
 #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 @@ GNUNET_RPS_request_peers_single_call (const struct GNUNET_CONFIGURATION_Handle *
 
 /**
  * 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 @@ GNUNET_RPS_connect( const struct GNUNET_CONFIGURATION_Handle *cfg );
  * 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 @@ GNUNET_RPS_request_peers (struct GNUNET_RPS_Handle *h, uint64_t n,
 
 /**
  * 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 );
-- 
cgit v1.2.3