[GNUnet-SVN] r25671 - in gnunet/src: include testbed

[gnunet]

Author: harsha
Date: 2013-01-02 10:30:42 +0100 (Wed, 02 Jan 2013)
New Revision: 25671

Modified:
   gnunet/src/include/gnunet_testbed_service.h
   gnunet/src/include/gnunet_testing_lib.h
   gnunet/src/testbed/testbed_api.c
   gnunet/src/testbed/testbed_api.h
   gnunet/src/testbed/testbed_api_hosts.c
Log:
- doxygen

Modified: gnunet/src/include/gnunet_testbed_service.h
===================================================================
--- gnunet/src/include/gnunet_testbed_service.h 2013-01-01 22:44:12 UTC (rev 
25670)
+++ gnunet/src/include/gnunet_testbed_service.h 2013-01-02 09:30:42 UTC (rev 
25671)
@@ -172,7 +172,7 @@
 /**
  * Function to cancel a request started using 
GNUNET_TESTBED_is_host_habitable()
  *
- * @param struct handle the habitability check handle
+ * @param handle the habitability check handle
  */
 void
 GNUNET_TESTBED_is_host_habitable_cancel (struct
@@ -1378,7 +1378,7 @@
  * @param cc_cls closure for cc
  * @param test_master this callback will be called once the test is ready
  * @param test_master_cls closure for 'test_master'.
- * @param GNUNET_SYSERR on error, GNUNET_OK on success
+ * @return GNUNET_SYSERR on error, GNUNET_OK on success
  */
 int
 GNUNET_TESTBED_test_run (const char *testname,

Modified: gnunet/src/include/gnunet_testing_lib.h
===================================================================
--- gnunet/src/include/gnunet_testing_lib.h     2013-01-01 22:44:12 UTC (rev 
25670)
+++ gnunet/src/include/gnunet_testing_lib.h     2013-01-02 09:30:42 UTC (rev 
25671)
@@ -95,9 +95,6 @@
  *          service configurations generated to allow control connections from
  *          this ip. This can either be a single ip address or a network 
address
  *          in CIDR notation.
- * @param controller hostname of the controlling host, 
- *        service configurations are modified to allow 
- *        control connections from this host; can be NULL
  * @param hostname the hostname of the system we are using for testing; NULL 
for
  *          localhost
  * @param lowport lowest port number this system is allowed to allocate 
(inclusive)

Modified: gnunet/src/testbed/testbed_api.c
===================================================================
--- gnunet/src/testbed/testbed_api.c    2013-01-01 22:44:12 UTC (rev 25670)
+++ gnunet/src/testbed/testbed_api.c    2013-01-02 09:30:42 UTC (rev 25671)
@@ -312,10 +312,10 @@
 
 
 /**
- * FIXME: doc
+ * Initialize standard deviation calculation handle
  *
- * @param 
- * @return 
+ * @param max_cnt the maximum number of readings to keep
+ * @return the initialized handle
  */
 static struct SDHandle *
 SD_init (unsigned int max_cnt)
@@ -330,10 +330,9 @@
 
 
 /**
- * FIXME: doc
+ * Frees the memory allocated to the SD handle
  *
- * @param 
- * @return 
+ * @param h the SD handle
  */
 static void
 SD_destroy (struct SDHandle *h)
@@ -348,6 +347,13 @@
   GNUNET_free (h);
 }
 
+
+/**
+ * Add a reading to SD
+ *
+ * @param h the SD handle
+ * @param amount the reading value
+ */
 static void
 SD_add_data (struct SDHandle *h, unsigned int amount)
 {
@@ -385,9 +391,10 @@
  *
  * @param h the SDhandle
  * @param amount the value for which the deviation is returned
+
  * @return the deviation from the average; GNUNET_SYSERR if the deviation 
cannot
- *           be calculated; a maximum of 4 is returned for deviations equal to
- *           or larger than 4
+ *           be calculated OR 0 if the deviation is less than the average; a
+ *           maximum of 4 is returned for deviations equal to or larger than 4
  */
 static int
 SD_deviation_factor (struct SDHandle *h, unsigned int amount)
@@ -1464,10 +1471,10 @@
 
 
 /**
- * FIXME: doc
+ * Initializes the operation queue for parallel overlay connects
  *
- * @param 
- * @return 
+ * @param c the controller handle
+ * @param npoc the number of parallel overlay connects - the queue size
  */
 static void
 GNUNET_TESTBED_set_num_parallel_overlay_connects_ (struct
@@ -1528,8 +1535,6 @@
  *          HOST(all connections form this ip are permitted by the testbed) 
when
  *          starting testbed controller at host. This can either be a single ip
  *          address or a network address in CIDR notation.
- * @param controller_ip the ip address of the controller. Will be set as 
TRUSTED
- *          host when starting testbed controller at host
  * @param host the host where the controller has to be started; NULL for
  *          localhost
  * @param cfg template configuration to use for the remote controller; the
@@ -2469,6 +2474,8 @@
  * Returns a timing slot which will be exclusively locked
  *
  * @param c the controller handle
+ * @param key a pointer which is associated to the returned slot; should not be
+ *          NULL. It serves as a key to determine the correct owner of the slot
  * @return the time slot index in the array of time slots in the controller
  *           handle
  */
@@ -2489,6 +2496,12 @@
 }
 
 
+/**
+ * Decides whether any change in the number of parallel overlay connects is
+ * necessary to adapt to the load on the system
+ *
+ * @param c the controller handle
+ */
 static void
 decide_npoc (struct GNUNET_TESTBED_Controller *c)
 {
@@ -2528,6 +2541,16 @@
 }
 
 
+/**
+ * Releases a time slot thus making it available for be used again
+ *
+ * @param c the controller handle
+ * @param index the index of the the time slot
+ * @param key the key to prove ownership of the timeslot
+ * @return GNUNET_YES if the time slot is successfully removed; GNUNET_NO if 
the
+ *           time slot cannot be removed - this could be because of the index
+ *           greater than existing number of time slots or `key' being 
different
+ */
 int
 GNUNET_TESTBED_release_time_slot_ (struct GNUNET_TESTBED_Controller *c,
                                   unsigned int index,
@@ -2551,6 +2574,7 @@
  *
  * @param c the controller handle
  * @param index the index of the time slot to update
+ * @param key the key to identify ownership of the slot
  * @param time the new time
  */
 void

Modified: gnunet/src/testbed/testbed_api.h
===================================================================
--- gnunet/src/testbed/testbed_api.h    2013-01-01 22:44:12 UTC (rev 25670)
+++ gnunet/src/testbed/testbed_api.h    2013-01-02 09:30:42 UTC (rev 25671)
@@ -379,9 +379,13 @@
 
 
 /**
- * Creates a helper initialization message. Only for testing.
+ * Creates a helper initialization message. This function is here because we
+ * want to use this in testing
  *
- * @param cname the ip address of the controlling host
+ * @param trusted_ip the ip address of the controller which will be set as 
TRUSTED
+ *          HOST(all connections form this ip are permitted by the testbed) 
when
+ *          starting testbed controller at host. This can either be a single ip
+ *          address or a network address in CIDR notation.
  * @param hostname the hostname of the destination this message is intended for
  * @param cfg the configuration that has to used to start the testbed service
  *          thru helper
@@ -535,10 +539,28 @@
                                 *slave_cfg,
                                  int is_subordinate);
 
+
+/**
+ * Returns a timing slot which will be exclusively locked
+ *
+ * @param c the controller handle
+ * @param key a pointer which is associated to the returned slot; should not be
+ *          NULL. It serves as a key to determine the correct owner of the slot
+ * @return the time slot index in the array of time slots in the controller
+ *           handle
+ */
 unsigned int
 GNUNET_TESTBED_get_tslot_ (struct GNUNET_TESTBED_Controller *c, void *key);
 
 
+/**
+ * Function to update a time slot
+ *
+ * @param c the controller handle
+ * @param index the index of the time slot to update
+ * @param key the key to identify ownership of the slot
+ * @param time the new time
+ */
 void
 GNUNET_TESTBED_update_time_slot_ (struct GNUNET_TESTBED_Controller *c,
                                   unsigned int index,
@@ -546,6 +568,16 @@
                                   struct GNUNET_TIME_Relative time);
 
 
+/**
+ * Releases a time slot thus making it available for be used again
+ *
+ * @param c the controller handle
+ * @param index the index of the the time slot
+ * @param key the key to prove ownership of the timeslot
+ * @return GNUNET_YES if the time slot is successfully removed; GNUNET_NO if 
the
+ *           time slot cannot be removed - this could be because of the index
+ *           greater than existing number of time slots or `key' being 
different
+ */
 int
 GNUNET_TESTBED_release_time_slot_ (struct GNUNET_TESTBED_Controller *c,
                                   unsigned int index,

Modified: gnunet/src/testbed/testbed_api_hosts.c
===================================================================
--- gnunet/src/testbed/testbed_api_hosts.c      2013-01-01 22:44:12 UTC (rev 
25670)
+++ gnunet/src/testbed/testbed_api_hosts.c      2013-01-02 09:30:42 UTC (rev 
25671)
@@ -646,7 +646,7 @@
 /**
  * Function to cancel a request started using 
GNUNET_TESTBED_is_host_habitable()
  *
- * @param struct handle the habitability check handle
+ * @param handle the habitability check handle
  */
 void
 GNUNET_TESTBED_is_host_habitable_cancel (struct