peerstore: doxygen

6 files changed, 96 insertions, 81 deletions

diff --git a/src/include/gnunet_peerstore_service.h b/src/include/gnunet_peerstore_service.h
index ca751af96..fcd0bb5f2 100644
--- a/src/include/gnunet_peerstore_service.h
+++ b/src/include/gnunet_peerstore_service.h
@@ -134,7 +134,8 @@ GNUNET_PEERSTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 
 /**
  * Disconnect from the PEERSTORE service. Any pending ITERATE and WATCH requests
- * will be canceled. Any pending STORE requests will depend on @snyc_first flag.
+ * will be canceled.
+ * Any pending STORE requests will depend on @e snyc_first flag.
  *
  * @param h handle to disconnect
  * @param sync_first send any pending STORE requests before disconnecting
@@ -143,30 +144,32 @@ void
 GNUNET_PEERSTORE_disconnect (struct GNUNET_PEERSTORE_Handle *h, int sync_first);
 
 /**
- * Store a new entry in the PEERSTORE
+ * Store a new entry in the PEERSTORE.
+ * Note that stored entries can be lost in some cases
+ * such as power failure.
  *
  * @param h Handle to the PEERSTORE service
  * @param sub_system name of the sub system
  * @param peer Peer Identity
  * @param key entry key
  * @param value entry value BLOB
- * @param size size of 'value'
+ * @param size size of @e value
  * @param expiry absolute time after which the entry is (possibly) deleted
- * @param options store operation option
- * @param cont Continuation function after the store request is processed
+ * @param options options specific to the storage operation
+ * @param cont Continuation function after the store request is sent
  * @param cont_cls Closure for 'cont'
  */
 struct GNUNET_PEERSTORE_StoreContext *
 GNUNET_PEERSTORE_store (struct GNUNET_PEERSTORE_Handle *h,
-    const char *sub_system,
-    const struct GNUNET_PeerIdentity *peer,
-    const char *key,
-    const void *value,
-    size_t size,
-    struct GNUNET_TIME_Absolute expiry,
-    enum GNUNET_PEERSTORE_StoreOption options,
-    GNUNET_PEERSTORE_Continuation cont,
-    void *cont_cls);
+                        const char *sub_system,
+                        const struct GNUNET_PeerIdentity *peer,
+                        const char *key,
+                        const void *value,
+                        size_t size,
+                        struct GNUNET_TIME_Absolute expiry,
+                        enum GNUNET_PEERSTORE_StoreOption options,
+                        GNUNET_PEERSTORE_Continuation cont,
+                        void *cont_cls);
 
 /**
  * Cancel a store request
@@ -226,7 +229,7 @@ GNUNET_PEERSTORE_watch (struct GNUNET_PEERSTORE_Handle *h,
 /**
  * Cancel a watch request
  *
- * @wc handle to the watch request
+ * @param wc handle to the watch request
  */
 void
 GNUNET_PEERSTORE_watch_cancel(struct GNUNET_PEERSTORE_WatchContext *wc);
diff --git a/src/peerstore/gnunet-service-peerstore.c b/src/peerstore/gnunet-service-peerstore.c
index b7128dda5..c93d2cc95 100644
--- a/src/peerstore/gnunet-service-peerstore.c
+++ b/src/peerstore/gnunet-service-peerstore.c
@@ -207,26 +207,29 @@ handle_client_disconnect (void *cls,
  * Function called by for each matching record.
  *
  * @param cls closure
- * @param peer peer identity
- * @param sub_system name of the GNUnet sub system responsible
- * @param value stored value
- * @param size size of stored value
+ * @param record peerstore record found
+ * @param emsg error message or NULL if no errors
+ * @return #GNUNET_YES to continue iteration
  */
-static int record_iterator(void *cls,
-    struct GNUNET_PEERSTORE_Record *record,
-    char *emsg)
+static int
+record_iterator (void *cls,
+                 struct GNUNET_PEERSTORE_Record *record,
+                 char *emsg)
 {
   struct GNUNET_SERVER_Client *client = cls;
   struct StoreRecordMessage *srm;
 
-  srm = PEERSTORE_create_record_message(record->sub_system,
-      record->peer,
-      record->key,
-      record->value,
-      record->value_size,
-      record->expiry,
-      GNUNET_MESSAGE_TYPE_PEERSTORE_ITERATE_RECORD);
-  GNUNET_SERVER_notification_context_unicast(nc, client, (struct GNUNET_MessageHeader *)srm, GNUNET_NO);
+  srm =
+      PEERSTORE_create_record_message(record->sub_system,
+                                      record->peer,
+                                      record->key,
+                                      record->value,
+                                      record->value_size,
+                                      record->expiry,
+                                      GNUNET_MESSAGE_TYPE_PEERSTORE_ITERATE_RECORD);
+  GNUNET_SERVER_notification_context_unicast (nc, client,
+                                              (struct GNUNET_MessageHeader *)srm,
+                                              GNUNET_NO);
   GNUNET_free(srm);
   return GNUNET_YES;
 }
@@ -348,17 +351,18 @@ static void handle_iterate (void *cls,
     GNUNET_SERVER_receive_done(client, GNUNET_SYSERR);
     return;
   }
-  GNUNET_log(GNUNET_ERROR_TYPE_DEBUG, "Iterate request: ss `%s', peer `%s', key `%s'\n",
-      record->sub_system,
-      (NULL == record->peer) ? "NULL" : GNUNET_i2s(record->peer),
-      (NULL == record->key) ? "NULL" : record->key);
+  GNUNET_log(GNUNET_ERROR_TYPE_DEBUG,
+             "Iterate request: ss `%s', peer `%s', key `%s'\n",
+             record->sub_system,
+             (NULL == record->peer) ? "NULL" : GNUNET_i2s(record->peer),
+             (NULL == record->key) ? "NULL" : record->key);
   GNUNET_SERVER_notification_context_add(nc, client);
   if(GNUNET_OK == db->iterate_records(db->cls,
-      record->sub_system,
-      record->peer,
-      record->key,
-      &record_iterator,
-      client))
+                                      record->sub_system,
+                                      record->peer,
+                                      record->key,
+                                      &record_iterator,
+                                      client))
   {
     endmsg = GNUNET_new(struct GNUNET_MessageHeader);
     endmsg->size = htons(sizeof(struct GNUNET_MessageHeader));
diff --git a/src/peerstore/peerstore_api.c b/src/peerstore/peerstore_api.c
index 81d287b53..3c67846e6 100644
--- a/src/peerstore/peerstore_api.c
+++ b/src/peerstore/peerstore_api.c
@@ -454,7 +454,8 @@ GNUNET_PEERSTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg)
 
 /**
  * Disconnect from the PEERSTORE service. Any pending ITERATE and WATCH requests
- * will be canceled. Any pending STORE requests will depend on @snyc_first flag.
+ * will be canceled.
+ * Any pending STORE requests will depend on @e snyc_first flag.
  *
  * @param h handle to disconnect
  * @param sync_first send any pending STORE requests before disconnecting
@@ -556,22 +557,23 @@ GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext *sc)
  * @param peer Peer Identity
  * @param key entry key
  * @param value entry value BLOB
- * @param size size of 'value'
+ * @param size size of @e value
  * @param expiry absolute time after which the entry is (possibly) deleted
+ * @param options options specific to the storage operation
  * @param cont Continuation function after the store request is sent
  * @param cont_cls Closure for 'cont'
  */
 struct GNUNET_PEERSTORE_StoreContext *
 GNUNET_PEERSTORE_store (struct GNUNET_PEERSTORE_Handle *h,
-    const char *sub_system,
-    const struct GNUNET_PeerIdentity *peer,
-    const char *key,
-    const void *value,
-    size_t size,
-    struct GNUNET_TIME_Absolute expiry,
-    enum GNUNET_PEERSTORE_StoreOption options,
-    GNUNET_PEERSTORE_Continuation cont,
-    void *cont_cls)
+                        const char *sub_system,
+                        const struct GNUNET_PeerIdentity *peer,
+                        const char *key,
+                        const void *value,
+                        size_t size,
+                        struct GNUNET_TIME_Absolute expiry,
+                        enum GNUNET_PEERSTORE_StoreOption options,
+                        GNUNET_PEERSTORE_Continuation cont,
+                        void *cont_cls)
 {
   struct GNUNET_MQ_Envelope *ev;
   struct GNUNET_PEERSTORE_StoreContext *sc;
@@ -580,13 +582,13 @@ GNUNET_PEERSTORE_store (struct GNUNET_PEERSTORE_Handle *h,
       "Storing value (size: %lu) for subsytem `%s', peer `%s', key `%s'\n",
       size, sub_system, GNUNET_i2s (peer), key);
   ev = PEERSTORE_create_record_mq_envelope(sub_system,
-      peer,
-      key,
-      value,
-      size,
-      &expiry,
-      options,
-      GNUNET_MESSAGE_TYPE_PEERSTORE_STORE);
+                                           peer,
+                                           key,
+                                           value,
+                                           size,
+                                           &expiry,
+                                           options,
+                                           GNUNET_MESSAGE_TYPE_PEERSTORE_STORE);
   sc = GNUNET_new(struct GNUNET_PEERSTORE_StoreContext);
   sc->ev = ev;
   sc->cont = cont;
@@ -681,6 +683,7 @@ static void iterate_request_sent (void *cls)
  * Called when the iterate request is timedout
  *
  * @param cls a 'struct GNUNET_PEERSTORE_IterateContext *'
+ * @param tc Scheduler task context (unused)
  */
 static void
 iterate_timeout (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
@@ -823,7 +826,7 @@ static void watch_request_sent (void *cls)
 /**
  * Cancel a watch request
  *
- * @wc handle to the watch request
+ * @param wc handle to the watch request
  */
 void
 GNUNET_PEERSTORE_watch_cancel(struct GNUNET_PEERSTORE_WatchContext *wc)
diff --git a/src/peerstore/peerstore_common.c b/src/peerstore/peerstore_common.c
index 384a68f39..0cb801cc4 100644
--- a/src/peerstore/peerstore_common.c
+++ b/src/peerstore/peerstore_common.c
@@ -127,18 +127,19 @@ PEERSTORE_create_record_message(const char *sub_system,
  * @param value record value BLOB (can be NULL)
  * @param value_size record value size in bytes (set to 0 if value is NULL)
  * @param expiry time after which the record expires
+ * @param options options specific to the storage operation
  * @param msg_type message type to be set in header
  * @return pointer to record message struct
  */
 struct GNUNET_MQ_Envelope *
 PEERSTORE_create_record_mq_envelope(const char *sub_system,
-    const struct GNUNET_PeerIdentity *peer,
-    const char *key,
-    const void *value,
-    size_t value_size,
-    struct GNUNET_TIME_Absolute *expiry,
-    enum GNUNET_PEERSTORE_StoreOption options,
-    uint16_t msg_type)
+                                    const struct GNUNET_PeerIdentity *peer,
+                                    const char *key,
+                                    const void *value,
+                                    size_t value_size,
+                                    struct GNUNET_TIME_Absolute *expiry,
+                                    enum GNUNET_PEERSTORE_StoreOption options,
+                                    uint16_t msg_type)
 {
   struct StoreRecordMessage *srm;
   struct GNUNET_MQ_Envelope *ev;
diff --git a/src/peerstore/peerstore_common.h b/src/peerstore/peerstore_common.h
index 297eb9fc0..50ff4a2f9 100644
--- a/src/peerstore/peerstore_common.h
+++ b/src/peerstore/peerstore_common.h
@@ -66,18 +66,19 @@ PEERSTORE_create_record_message(const char *sub_system,
  * @param value record value BLOB (can be NULL)
  * @param value_size record value size in bytes (set to 0 if value is NULL)
  * @param expiry time after which the record expires
+ * @param options options specific to the storage operation
  * @param msg_type message type to be set in header
  * @return pointer to record message struct
  */
 struct GNUNET_MQ_Envelope *
 PEERSTORE_create_record_mq_envelope(const char *sub_system,
-    const struct GNUNET_PeerIdentity *peer,
-    const char *key,
-    const void *value,
-    size_t value_size,
-    struct GNUNET_TIME_Absolute *expiry,
-    enum GNUNET_PEERSTORE_StoreOption options,
-    uint16_t msg_type);
+                                    const struct GNUNET_PeerIdentity *peer,
+                                    const char *key,
+                                    const void *value,
+                                    size_t value_size,
+                                    struct GNUNET_TIME_Absolute *expiry,
+                                    enum GNUNET_PEERSTORE_StoreOption options,
+                                    uint16_t msg_type);
 
 /**
  * Parses a message carrying a record
diff --git a/src/peerstore/plugin_peerstore_sqlite.c b/src/peerstore/plugin_peerstore_sqlite.c
index 0a0df4b0c..2726eef3d 100644
--- a/src/peerstore/plugin_peerstore_sqlite.c
+++ b/src/peerstore/plugin_peerstore_sqlite.c
@@ -284,21 +284,24 @@ peerstore_sqlite_iterate_records (void *cls,
  * One key can store multiple values.
  *
  * @param cls closure (internal context for the plugin)
- * @param peer peer identity
  * @param sub_system name of the GNUnet sub system responsible
+ * @param peer peer identity
+ * @param key record key string
  * @param value value to be stored
  * @param size size of value to be stored
+ * @param expiry absolute time after which the record is (possibly) deleted
+ * @param options options related to the store operation
  * @return #GNUNET_OK on success, else #GNUNET_SYSERR
  */
 static int
-peerstore_sqlite_store_record(void *cls,
-    const char *sub_system,
-    const struct GNUNET_PeerIdentity *peer,
-    const char *key,
-    const void *value,
-    size_t size,
-    struct GNUNET_TIME_Absolute expiry,
-    enum GNUNET_PEERSTORE_StoreOption options)
+peerstore_sqlite_store_record (void *cls,
+                               const char *sub_system,
+                               const struct GNUNET_PeerIdentity *peer,
+                               const char *key,
+                               const void *value,
+                               size_t size,
+                               struct GNUNET_TIME_Absolute expiry,
+                               enum GNUNET_PEERSTORE_StoreOption options)
 {
   struct Plugin *plugin = cls;
   sqlite3_stmt *stmt = plugin->insert_peerstoredata;