psyc apis: use more doxygen syntax, added some missing docs

1 files changed, 112 insertions, 22 deletions

diff --git a/src/include/gnunet_psycstore_service.h b/src/include/gnunet_psycstore_service.h
index 701f6940f..30671cda2 100644
--- a/src/include/gnunet_psycstore_service.h
+++ b/src/include/gnunet_psycstore_service.h
@@ -18,10 +18,10 @@
      Boston, MA 02111-1307, USA.
 */
 
-/**
+/** 
  * @file include/gnunet_psycstore_service.h
  * @brief PSYCstore service; implements persistent storage for the PSYC service
- * @author tg
+ * @author tg(x)
  * @author Christian Grothoff
  */
 #ifndef GNUNET_PSYCSTORE_SERVICE_H
@@ -37,18 +37,18 @@ extern "C"
 
 #include "gnunet_util_lib.h"
 
-/**
+/** 
  * Version number of GNUnet PSYCstore API.
  */
 #define GNUNET_PSYCSTORE_VERSION 0x00000000
 
-/**
+/** 
  * Handle for a PSYCstore
  */
 struct GNUNET_PSYCSTORE_Handle;
 
 
-/**
+/** 
  * Connect to the PSYCstore service.
  *
  * @param cfg Configuration to use.
@@ -59,7 +59,7 @@ struct GNUNET_PSYCSTORE_Handle *
 GNUNET_PSYCSTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 
 
-/**
+/** 
  * Disconnect from the PSYCstore service.
  *
  * @param h Handle for the connection.
@@ -68,22 +68,23 @@ void
 GNUNET_PSYCSTORE_disconnect (struct GNUNET_PSYCSTORE_Handle *h);
 
 
-/**
+/** 
  * Handle for an operation on the PSYCSTORE (useful to cancel the operation).
  */
 struct GNUNET_PSYCSTORE_OperationHandle;
 
 
-/**
- *
- * @param result GNUNET_SYSERR on error,
- *        GNUNET_YES on success or if the peer was a member,
- *        GNUNET_NO if the peer was not a member
+/** 
+ * Function called with the result of an asynchronous operation.
+; * 
+ * @param result #GNUNET_SYSERR on error,
+ *        #GNUNET_YES on success or if the peer was a member,
+ *        #GNUNET_NO if the peer was not a member
  */
 typedef void (*GNUNET_PSYCSTORE_ContinuationCallback)(void *cls,
                                                       int result);
 
-/**
+/** 
  * Store join/leave events for a PSYC channel in order to be able to answer
  * membership test queries later.
  *
@@ -91,7 +92,7 @@ typedef void (*GNUNET_PSYCSTORE_ContinuationCallback)(void *cls,
  * @param channel_id ID of the channel where the event happened.
  * @param message_id ID of the message in which this event was announced.
  * @param peer Identity of joining/leaving peer.
- * @param did_join GNUNET_YES on join, GNUNET_NO on leave.
+ * @param did_join #GNUNET_YES on join, #GNUNET_NO on leave.
  * @param ccb Callback to call with the result of the storage operation.
  * @param ccb_cls Closure for the callback.
  *
@@ -107,11 +108,12 @@ GNUNET_PSYCSTORE_membership_store (struct GNUNET_PSYCSTORE_Handle *h,
                                    void *ccb_cls);
 
 
-/**
+/** 
  * Test if a peer was a member of the channel when the message with the
- * specified ID was sent to the channel. This is useful in case of
- * retransmissions to check if the peer was authorized to see the requested
- * message.
+ * specified ID was sent to the channel.
+ *
+ * This is useful in case of retransmissions to check if the peer was authorized
+ * to see the requested message.
  *
  * @param h Handle for the PSYCstore.
  * @param channel_id The channel we are interested in.
@@ -121,7 +123,8 @@ GNUNET_PSYCSTORE_membership_store (struct GNUNET_PSYCSTORE_Handle *h,
  * @param ccb_cls Closure for the callback.
  *
  * @return Operation handle that can be used to cancel the operation.
- */struct GNUNET_PSYCSTORE_OperationHandle *
+ */
+struct GNUNET_PSYCSTORE_OperationHandle *
 GNUNET_PSYCSTORE_membership_test (struct GNUNET_PSYCSTORE_Handle *h,
                                   const struct GNUNET_HashCode *channel_id,
                                   uint64_t message_id,
@@ -130,6 +133,17 @@ GNUNET_PSYCSTORE_membership_test (struct GNUNET_PSYCSTORE_Handle *h,
                                   void *ccb_cls);
 
 
+/** 
+ * Store a message sent to a channel.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel the message belongs to.
+ * @param message_id Message ID to store.
+ * @param ccb Callback to call with the result of the operation.
+ * @param ccb_cls Closure for the callback.
+ * 
+ * @return Handle that can be used to cancel the operation.
+ */
 struct GNUNET_PSYCSTORE_OperationHandle *
 GNUNET_PSYCSTORE_message_store (struct GNUNET_PSYCSTORE_Handle *h,
                                 const struct GNUNET_HashCode *channel_id,
@@ -138,11 +152,29 @@ GNUNET_PSYCSTORE_message_store (struct GNUNET_PSYCSTORE_Handle *h,
                                 void *ccb_cls);
 
 
+/** 
+ * Function called with the result of a GNUNET_PSYCSTORE_message_get() call.
+ *
+ * @param cls Closure.
+ * @param message_id ID of the message.
+ * @param message The retrieved message.
+ */
 typedef void (*GNUNET_PSYCSTORE_MessageResultCallback)(void *cls,       
                                                        uint64_t message_id,                                    
                                                        const struct GNUNET_MULTICAST_MessageHeader *message);
 
 
+/** 
+ * Retrieve a message by ID.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel we are interested in.
+ * @param message_id Message ID to check.
+ * @param rcb Callback to call with the result of the operation.
+ * @param rcb_cls Closure for the callback.
+ * 
+ * @return Handle that can be used to cancel the operation.
+ */
 struct GNUNET_PSYCSTORE_OperationHandle *
 GNUNET_PSYCSTORE_message_get (struct GNUNET_PSYCSTORE_Handle *h,
                               const struct GNUNET_HashCode *channel_id,
@@ -151,6 +183,16 @@ GNUNET_PSYCSTORE_message_get (struct GNUNET_PSYCSTORE_Handle *h,
                               void *rcb_cls);
 
 
+/** 
+ * Get latest message sent to a channel.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel we are interested in.
+ * @param rcb Callback to call with the result of the operation.
+ * @param rcb_cls Closure for the callback.
+ * 
+ * @return Handle that can be used to cancel the operation.
+ */
 struct GNUNET_PSYCSTORE_OperationHandle *
 GNUNET_PSYCSTORE_message_get_latest (struct GNUNET_PSYCSTORE_Handle *h,
                                      const struct GNUNET_HashCode *channel_id,
@@ -158,30 +200,73 @@ GNUNET_PSYCSTORE_message_get_latest (struct GNUNET_PSYCSTORE_Handle *h,
                                      void *rcb_cls);
 
 
+/** 
+ * Store a state variable.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel we are interested in.
+ * @param name Name of variable.
+ * @param size Size of @a value.
+ * @param value Value of variable.
+ * @param ccb Callback to call with the result of the operation.
+ * @param ccb_cls Closure for the callback.
+ * 
+ * @return Handle that can be used to cancel the operation.
+ */
 struct GNUNET_PSYCSTORE_OperationHandle *
 GNUNET_PSYCSTORE_state_set (struct GNUNET_PSYCSTORE_Handle *h,
                             const struct GNUNET_HashCode *channel_id,
-                            const char *state_name,
+                            const char *name,
                             size_t size,
                             const void *value,
                             GNUNET_PSYCSTORE_ContinuationCallback ccb,
                             void *ccb_cls);
 
 
+/** 
+ * Function called with the value of a state variable.
+ *
+ * @param cls Closure.
+ * @param name Name of variable.
+ * @param size Size of @a value.
+ * @param value Value of variable.
+t * 
+ */
 typedef void (*GNUNET_PSYCSTORE_StateResultCallback)(void *cls,
-                                                     const char *state_name,
+                                                     const char *name,
                                                      size_t size,
                                                      const void *value);
 
 
+/** 
+ * Retrieve the given state variable for a channel.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel we are interested in.
+ * @param name Name of variable to get.
+ * @param rcb Callback to call with the result.
+ * @param rcb_cls Closure for the callback.
+ * 
+ * @return Handle that can be used to cancel the operation.
+ */
 struct GNUNET_PSYCSTORE_OperationHandle *
 GNUNET_PSYCSTORE_state_get (struct GNUNET_PSYCSTORE_Handle *h,
                             const struct GNUNET_HashCode *channel_id,
-                            const char *state_name,
+                            const char *name,
                             GNUNET_PSYCSTORE_StateResultCallback rcb,
                             void *rcb_cls);
 
 
+/** 
+ * Retrieve all state variables for a channel.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel we are interested in.
+ * @param rcb Callback to call with the result.
+ * @param rcb_cls Closure for the callback.
+ * 
+ * @return Handle that can be used to cancel the operation.
+ */
 struct GNUNET_PSYCSTORE_OperationHandle *
 GNUNET_PSYCSTORE_state_get_all (struct GNUNET_PSYCSTORE_Handle *h,
                                 const struct GNUNET_HashCode *channel_id,
@@ -189,6 +274,11 @@ GNUNET_PSYCSTORE_state_get_all (struct GNUNET_PSYCSTORE_Handle *h,
                                 void *rcb_cls);
 
 
+/** 
+ * Cancel an operation.
+ *
+ * @param oh Handle for the operation to cancel.
+ */
 void
 GNUNET_PSYCSTORE_operation_cancel (struct GNUNET_PSYCSTORE_OperationHandle *oh);