-doxygen fixes, and fixing publish URI serization for proper resume

8 files changed, 92 insertions, 59 deletions

diff --git a/src/fs/fs_api.c b/src/fs/fs_api.c
index 1efda5a828..c2e2ada3ed 100644
--- a/src/fs/fs_api.c
+++ b/src/fs/fs_api.c
@@ -1044,7 +1044,8 @@ cleanup:
  * @return NULL on error
  */
 static struct GNUNET_FS_FileInformation *
-deserialize_file_information (struct GNUNET_FS_Handle *h, const char *filename)
+deserialize_file_information (struct GNUNET_FS_Handle *h,
+			      const char *filename)
 {
   struct GNUNET_FS_FileInformation *ret;
   struct GNUNET_BIO_ReadHandle *rh;
@@ -1726,9 +1727,9 @@ cleanup:
 /**
  * Serialize a download request.
  *
- * @param wh the 'struct GNUNET_BIO_WriteHandle*'
- * @param dr the 'struct DownloadRequest'
- * @return GNUNET_YES on success, GNUNET_NO on error
+ * @param wh the `struct GNUNET_BIO_WriteHandle*`
+ * @param dr the the request to write to disk
+ * @return #GNUNET_YES on success, #GNUNET_NO on error
  */
 static int
 write_download_request (struct GNUNET_BIO_WriteHandle *wh,
@@ -1756,7 +1757,7 @@ write_download_request (struct GNUNET_BIO_WriteHandle *wh,
  * Read a download request tree.
  *
  * @param rh mesh to read from
- * @return value the 'struct DownloadRequest', NULL on error
+ * @return value the download request read from disk, NULL on error
  */
 static struct DownloadRequest *
 read_download_request (struct GNUNET_BIO_ReadHandle *rh)
diff --git a/src/fs/fs_download.c b/src/fs/fs_download.c
index 1175fcd05e..2b67dc31e4 100644
--- a/src/fs/fs_download.c
+++ b/src/fs/fs_download.c
@@ -2021,7 +2021,7 @@ GNUNET_FS_download_signal_suspend_ (void *cls)
   GNUNET_FS_download_make_status_ (&pi, dc);
   if (NULL != dc->te)
   {
-    GNUNET_FS_tree_encoder_finish (dc->te, NULL, NULL);
+    GNUNET_FS_tree_encoder_finish (dc->te, NULL);
     dc->te = NULL;
   }
   if (NULL != dc->rfh)
@@ -2310,7 +2310,7 @@ GNUNET_FS_download_stop (struct GNUNET_FS_DownloadContext *dc, int do_delete)
   }
   if (NULL != dc->te)
   {
-    GNUNET_FS_tree_encoder_finish (dc->te, NULL, NULL);
+    GNUNET_FS_tree_encoder_finish (dc->te, NULL);
     dc->te = NULL;
   }
   have_children = (NULL != dc->child_head) ? GNUNET_YES : GNUNET_NO;
diff --git a/src/fs/fs_file_information.c b/src/fs/fs_file_information.c
index b1ec1ed5d1..ad3dda05b7 100644
--- a/src/fs/fs_file_information.c
+++ b/src/fs/fs_file_information.c
@@ -451,7 +451,7 @@ GNUNET_FS_file_information_destroy (struct GNUNET_FS_FileInformation *fi,
   GNUNET_free_non_null (fi->serialization);
   if (NULL != fi->te)
   {
-    GNUNET_FS_tree_encoder_finish (fi->te, NULL, NULL);
+    GNUNET_FS_tree_encoder_finish (fi->te, NULL);
     fi->te = NULL;
   }
   GNUNET_free (fi);
diff --git a/src/fs/fs_publish.c b/src/fs/fs_publish.c
index 73af99ce9d..224f0c35ee 100644
--- a/src/fs/fs_publish.c
+++ b/src/fs/fs_publish.c
@@ -213,7 +213,8 @@ finish_release_reserve (void *cls, int success,
   struct GNUNET_FS_PublishContext *pc = cls;
 
   pc->qre = NULL;
-  GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "Releasing reserve done!\n");
+  GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, 
+	      "Releasing reserve done!\n");
   signal_publish_completion (pc->fi, pc);
   pc->all_done = GNUNET_YES;
   GNUNET_FS_publish_sync_ (pc);
@@ -299,7 +300,8 @@ publish_kblocks_cont (void *cls, const struct GNUNET_FS_Uri *uri,
   pc->ksk_pc = NULL;
   if (NULL != emsg)
   {
-    GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "Error uploading KSK blocks: %s\n",
+    GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, 
+		"Error uploading KSK blocks: %s\n",
                 emsg);
     signal_publish_error (p, pc, emsg);
     GNUNET_FS_file_information_sync_ (p);
@@ -396,15 +398,21 @@ encode_cont (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
   char *emsg;
   uint64_t flen;
 
-  GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "Finished with tree encoder\n");
+  GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
+	      "Finished with tree encoder\n");
   p = pc->fi_pos;
+  p->chk_uri = GNUNET_FS_tree_encoder_get_uri (p->te);
   GNUNET_FS_file_information_sync_ (p);
-  GNUNET_FS_tree_encoder_finish (p->te, &p->chk_uri, &emsg);
+  GNUNET_FS_tree_encoder_finish (p->te, &emsg);
   p->te = NULL;
   if (NULL != emsg)
   {
-    GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "Error during tree walk: %s\n", emsg);
-    GNUNET_asprintf (&p->emsg, _("Publishing failed: %s"), emsg);
+    GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
+		"Error during tree walk: %s\n", 
+		emsg);
+    GNUNET_asprintf (&p->emsg,
+		     _("Publishing failed: %s"), 
+		     emsg);
     GNUNET_free (emsg);
     pi.status = GNUNET_FS_STATUS_PUBLISH_ERROR;
     pi.value.publish.eta = GNUNET_TIME_UNIT_FOREVER_REL;
@@ -434,8 +442,8 @@ encode_cont (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
 /**
  * Function called asking for the current (encoded)
  * block to be processed.  After processing the
- * client should either call "GNUNET_FS_tree_encode_next"
- * or (on error) "GNUNET_FS_tree_encode_finish".
+ * client should either call #GNUNET_FS_tree_encode_next
+ * or (on error) #GNUNET_FS_tree_encode_finish.
  *
  * @param cls closure
  * @param chk content hash key for the block
@@ -465,8 +473,9 @@ block_proc (void *cls, const struct ContentHashKey *chk, uint64_t offset,
     return;
   }
 
-  if ((p->is_directory != GNUNET_YES) && (GNUNET_YES == p->data.file.do_index) &&
-      (type == GNUNET_BLOCK_TYPE_FS_DBLOCK))
+  if ( (GNUNET_YES != p->is_directory) &&
+       (GNUNET_YES == p->data.file.do_index) &&
+       (GNUNET_BLOCK_TYPE_FS_DBLOCK == type) )
   {
     GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
                 "Indexing block `%s' for offset %llu with index size %u\n",
@@ -546,17 +555,17 @@ publish_content (struct GNUNET_FS_PublishContext *pc)
   uint64_t size;
 
   p = pc->fi_pos;
-  GNUNET_assert (p != NULL);
+  GNUNET_assert (NULL != p);
   if (NULL == p->te)
   {
-    if (p->is_directory == GNUNET_YES)
+    if (GNUNET_YES == p->is_directory)
     {
       GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "Creating directory\n");
       db = GNUNET_FS_directory_builder_create (p->meta);
       dirpos = p->data.dir.entries;
       while (NULL != dirpos)
       {
-        if (dirpos->is_directory == GNUNET_YES)
+        if (GNUNET_YES == dirpos->is_directory)
         {
           raw_data = dirpos->data.dir.dir_data;
           dirpos->data.dir.dir_data = NULL;
@@ -593,15 +602,17 @@ publish_content (struct GNUNET_FS_PublishContext *pc)
                                           &p->data.dir.dir_data);
       GNUNET_FS_file_information_sync_ (p);
     }
-    size = (p->is_directory == GNUNET_YES) ? p->data.dir.dir_size : p->data.file.file_size;
-    GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "Creating tree encoder\n");
+    size = (GNUNET_YES == p->is_directory) ? p->data.dir.dir_size : p->data.file.file_size;
+    GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, 
+		"Creating tree encoder\n");
     p->te =
         GNUNET_FS_tree_encoder_create (pc->h, size, pc, &block_reader,
                                        &block_proc, &progress_proc,
                                        &encode_cont);
 
   }
-  GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "Processing next block from tree\n");
+  GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
+	      "Processing next block from tree\n");
   GNUNET_FS_tree_encoder_next (p->te);
 }
 
@@ -625,11 +636,10 @@ process_index_start_response (void *cls,
   GNUNET_CLIENT_disconnect (pc->client);
   pc->client = NULL;
   p = pc->fi_pos;
-  if (msg == NULL)
+  if (NULL == msg)
   {
     GNUNET_log (GNUNET_ERROR_TYPE_WARNING,
-                _
-                ("Can not index file `%s': %s.  Will try to insert instead.\n"),
+                _("Can not index file `%s': %s.  Will try to insert instead.\n"),
                 p->filename,
                 _("timeout on index-start request to `fs' service"));
     p->data.file.do_index = GNUNET_NO;
@@ -685,9 +695,9 @@ hash_for_index_cb (void *cls,
   if (NULL == res)
   {
     GNUNET_log (GNUNET_ERROR_TYPE_WARNING,
-                _
-                ("Can not index file `%s': %s.  Will try to insert instead.\n"),
-                p->filename, _("failed to compute hash"));
+                _("Can not index file `%s': %s.  Will try to insert instead.\n"),
+                p->filename, 
+		_("failed to compute hash"));
     p->data.file.do_index = GNUNET_NO;
     GNUNET_FS_file_information_sync_ (p);
     publish_content (pc);
@@ -730,9 +740,9 @@ hash_for_index_cb (void *cls,
   if (NULL == client)
   {
     GNUNET_log (GNUNET_ERROR_TYPE_WARNING,
-                _
-                ("Can not index file `%s': %s.  Will try to insert instead.\n"),
-                p->filename, _("could not connect to `fs' service"));
+                _("Can not index file `%s': %s.  Will try to insert instead.\n"),
+                p->filename, 
+		_("could not connect to `fs' service"));
     p->data.file.do_index = GNUNET_NO;
     publish_content (pc);
     GNUNET_free (fn);
@@ -854,10 +864,11 @@ GNUNET_FS_publish_main_ (void *cls,
                                     p->bo.expiration_time);
       GNUNET_FS_uri_destroy (p->chk_uri);
       p->chk_uri = loc;
+      GNUNET_FS_file_information_sync_ (p);
     }
     GNUNET_FS_publish_sync_ (pc);
     /* upload of "p" complete, publish KBlocks! */
-    if (p->keywords != NULL)
+    if (NULL != p->keywords)
     {
       pc->ksk_pc = GNUNET_FS_publish_ksk (pc->h, p->keywords, p->meta, p->chk_uri, &p->bo,
 					  pc->options, &publish_kblocks_cont, pc);
@@ -868,7 +879,7 @@ GNUNET_FS_publish_main_ (void *cls,
     }
     return;
   }
-  if ((p->is_directory != GNUNET_YES) && (p->data.file.do_index))
+  if ((GNUNET_YES != p->is_directory) && (p->data.file.do_index))
   {
     if (NULL == p->filename)
     {
@@ -932,7 +943,8 @@ fip_signal_start (void *cls,
     pc->skip_next_fi_callback = GNUNET_NO;
     return GNUNET_OK;
   }
-  GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "Starting publish operation\n");
+  GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
+	      "Starting publish operation\n");
   if (*do_index)
   {
     /* space for on-demand blocks */
@@ -1001,10 +1013,11 @@ suspend_operation (struct GNUNET_FS_FileInformation *fi,
     GNUNET_FS_publish_sks_cancel (pc->sks_pc);
     pc->sks_pc = NULL;
   }
-  GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "Suspending publish operation\n");
+  GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, 
+	      "Suspending publish operation\n");
   GNUNET_free_non_null (fi->serialization);
   fi->serialization = NULL;
-  off = (fi->chk_uri == NULL) ? 0 : (fi->is_directory == GNUNET_YES) ? fi->data.dir.dir_size : fi->data.file.file_size;
+  off = (NULL == fi->chk_uri) ? 0 : (GNUNET_YES == fi->is_directory) ? fi->data.dir.dir_size : fi->data.file.file_size;
   pi.status = GNUNET_FS_STATUS_PUBLISH_SUSPEND;
   GNUNET_break (NULL == GNUNET_FS_publish_make_status_ (&pi, pc, fi, off));
   if (NULL != pc->qre)
@@ -1025,7 +1038,7 @@ suspend_operation (struct GNUNET_FS_FileInformation *fi,
  * Signal the FS's progress function that we are suspending
  * an upload.  Performs the recursion.
  *
- * @param cls closure (of type "struct GNUNET_FS_PublishContext*")
+ * @param cls closure (of type `struct GNUNET_FS_PublishContext *`)
  * @param fi the entry in the publish-structure
  * @param length length of the file or directory
  * @param meta metadata for the file or directory (can be modified)
@@ -1068,7 +1081,7 @@ fip_signal_suspend (void *cls,
  * Create SUSPEND event for the given publish operation
  * and then clean up our state (without stop signal).
  *
- * @param cls the 'struct GNUNET_FS_PublishContext' to signal for
+ * @param cls the `struct GNUNET_FS_PublishContext` to signal for
  */
 void
 GNUNET_FS_publish_signal_suspend_ (void *cls)
diff --git a/src/fs/fs_tree.c b/src/fs/fs_tree.c
index 7629898244..b9dd894f56 100644
--- a/src/fs/fs_tree.c
+++ b/src/fs/fs_tree.c
@@ -416,19 +416,33 @@ GNUNET_FS_tree_encoder_next (struct GNUNET_FS_TreeEncoder *te)
 
 
 /**
+ * Get the resulting URI from the encoding.
+ *
+ * @param te the tree encoder to clean up
+ * @return uri set to the resulting URI (if encoding finished), NULL otherwise
+ */
+struct GNUNET_FS_Uri *
+GNUNET_FS_tree_encoder_get_uri (struct GNUNET_FS_TreeEncoder *te)
+{
+  if (NULL != te->uri)
+    return GNUNET_FS_uri_dup (te->uri);
+  return NULL;
+}
+
+
+/**
  * Clean up a tree encoder and return information
- * about the resulting URI or an error message.
+ * about possible errors.
  *
  * @param te the tree encoder to clean up
- * @param uri set to the resulting URI (if encoding finished)
  * @param emsg set to an error message (if an error occured
  *        within the tree encoder; if this function is called
  *        prior to completion and prior to an internal error,
- *        both "*uri" and "*emsg" will be set to NULL).
+ *        both "*emsg" will be set to NULL).
  */
 void
 GNUNET_FS_tree_encoder_finish (struct GNUNET_FS_TreeEncoder *te,
-                               struct GNUNET_FS_Uri **uri, char **emsg)
+			       char **emsg)
 {
   if (NULL != te->reader)
   {
@@ -436,9 +450,7 @@ GNUNET_FS_tree_encoder_finish (struct GNUNET_FS_TreeEncoder *te,
     te->reader =  NULL;
   }
   GNUNET_assert (GNUNET_NO == te->in_next);
-  if (uri != NULL)
-    *uri = te->uri;
-  else if (NULL != te->uri)
+  if (NULL != te->uri)
     GNUNET_FS_uri_destroy (te->uri);
   if (emsg != NULL)
     *emsg = te->emsg;
diff --git a/src/fs/fs_tree.h b/src/fs/fs_tree.h
index 5b1c2024f4..cd25a6dd14 100644
--- a/src/fs/fs_tree.h
+++ b/src/fs/fs_tree.h
@@ -158,19 +158,28 @@ GNUNET_FS_tree_encoder_next (struct GNUNET_FS_TreeEncoder *te);
 
 
 /**
+ * Get the resulting URI from the encoding.
+ *
+ * @param te the tree encoder to clean up
+ * @return uri set to the resulting URI (if encoding finished), NULL otherwise
+ */
+struct GNUNET_FS_Uri *
+GNUNET_FS_tree_encoder_get_uri (struct GNUNET_FS_TreeEncoder *te);
+
+
+/**
  * Clean up a tree encoder and return information
- * about the resulting URI or an error message.
+ * about possible errors.
  *
  * @param te the tree encoder to clean up
- * @param uri set to the resulting URI (if encoding finished)
  * @param emsg set to an error message (if an error occured
  *        within the tree encoder; if this function is called
  *        prior to completion and prior to an internal error,
- *        both "*uri" and "*emsg" will be set to NULL).
+ *        both "*emsg" will be set to NULL).
  */
 void
 GNUNET_FS_tree_encoder_finish (struct GNUNET_FS_TreeEncoder *te,
-                               struct GNUNET_FS_Uri **uri, char **emsg);
+                               char **emsg);
 
 
 #if 0
@@ -200,6 +209,7 @@ GNUNET_FS_tree_encoder_resume_get_data (const struct GNUNET_FS_TreeEncoder *te,
 void
 GNUNET_FS_tree_encoder_resume (struct GNUNET_FS_TreeEncoder *te,
                                const void *data, size_t size);
+
 #endif
 
 #endif
diff --git a/src/fs/fs_unindex.c b/src/fs/fs_unindex.c
index bb3accb823..ecf14112cf 100644
--- a/src/fs/fs_unindex.c
+++ b/src/fs/fs_unindex.c
@@ -271,15 +271,12 @@ static void
 unindex_finish (struct GNUNET_FS_UnindexContext *uc)
 {
   char *emsg;
-  struct GNUNET_FS_Uri *uri;
   struct UnindexMessage req;
 
   /* generate final progress message */
   unindex_progress (uc, uc->file_size, NULL, 0, 0);
-  GNUNET_FS_tree_encoder_finish (uc->tc, &uri, &emsg);
+  GNUNET_FS_tree_encoder_finish (uc->tc, &emsg);
   uc->tc = NULL;
-  if (uri != NULL)
-    GNUNET_FS_uri_destroy (uri);
   GNUNET_DISK_file_close (uc->fh);
   uc->fh = NULL;
   GNUNET_DATASTORE_disconnect (uc->dsh, GNUNET_NO);
@@ -730,7 +727,7 @@ GNUNET_FS_unindex_signal_suspend_ (void *cls)
   }
   if (NULL != uc->tc)
   {
-    GNUNET_FS_tree_encoder_finish (uc->tc, NULL, NULL);
+    GNUNET_FS_tree_encoder_finish (uc->tc, NULL);
     uc->tc = NULL;
   }
   if (uc->fh != NULL)
@@ -831,7 +828,7 @@ GNUNET_FS_unindex_stop (struct GNUNET_FS_UnindexContext *uc)
   }
   if (NULL != uc->tc)
   {
-    GNUNET_FS_tree_encoder_finish (uc->tc, NULL, NULL);
+    GNUNET_FS_tree_encoder_finish (uc->tc, NULL);
     uc->tc = NULL;
   }
   if (uc->fh != NULL)
diff --git a/src/util/container_meta_data.c b/src/util/container_meta_data.c
index 780ee612d6..777e0b6c35 100644
--- a/src/util/container_meta_data.c
+++ b/src/util/container_meta_data.c
@@ -211,7 +211,7 @@ GNUNET_CONTAINER_meta_data_clear (struct GNUNET_CONTAINER_MetaData *md)
  *
  * @param md1 first value to check
  * @param md2 other value to check
- * @return GNUNET_YES if they are equal
+ * @return #GNUNET_YES if they are equal
  */
 int
 GNUNET_CONTAINER_meta_data_test_equal (const struct GNUNET_CONTAINER_MetaData
@@ -343,7 +343,7 @@ GNUNET_CONTAINER_meta_data_insert (struct GNUNET_CONTAINER_MetaData *md,
 /**
  * Merge given meta data.
  *
- * @param cls the 'struct GNUNET_CONTAINER_MetaData' to merge into
+ * @param cls the `struct GNUNET_CONTAINER_MetaData` to merge into
  * @param plugin_name name of the plugin that produced this value;
  *        special values can be used (i.e. '<zlib>' for zlib being
  *        used in the main libextractor library and yielding