[GNUnet-SVN] r29158 - gnunet-gtk/src/fs

[gnunet]

Author: grothoff
Date: 2013-09-10 13:53:38 +0200 (Tue, 10 Sep 2013)
New Revision: 29158

Modified:
   gnunet-gtk/src/fs/gnunet-fs-gtk_event-handler.c
Log:
-doxygen fixes

Modified: gnunet-gtk/src/fs/gnunet-fs-gtk_event-handler.c
===================================================================
--- gnunet-gtk/src/fs/gnunet-fs-gtk_event-handler.c     2013-09-10 11:30:48 UTC 
(rev 29157)
+++ gnunet-gtk/src/fs/gnunet-fs-gtk_event-handler.c     2013-09-10 11:53:38 UTC 
(rev 29158)
@@ -316,6 +316,11 @@
 static struct GNUNET_FS_AnimationContext *animation_error;
 
 
+/** 
+ * Get the handle to the current search tab.
+ * 
+ * @return handle to the current search tab.
+ */
 struct SearchTab *
 GNUNET_FS_GTK_get_current_search_tab ()
 {
@@ -325,7 +330,12 @@
 
 /* ***************** Search event handling ****************** */
 
-
+/** 
+ * Load an animation.
+ * 
+ * @param basename basename of the animation file to load
+ * @return handle to the animation.
+ */
 static struct GNUNET_FS_AnimationContext *
 load_animation (const char *basename)
 {
@@ -366,8 +376,12 @@
  * somewhere else, at least until application restart, or maybe even
  * between application restarts).
  *
- * Fills the 'buffer' up to 'size' bytes, returns a pointer to it.
+ * Fills the @a buffer up to @a size bytes, returns a pointer to it.
  * Buffer will be NUL-terminated, if not NULL.
+ * 
+ * @param buffer where to store the download directory name
+ * @param size number of bytes available in @a buffer
+ * @return 
  */
 static char *
 get_default_download_directory (char *buffer, size_t size)
@@ -401,16 +415,21 @@
   return buffer;
 }
 
-/**
- * finished_chain - non-NULL for top-level call (for the item we're about to 
download), NULL otherwise
- *   function sets it to GNUNET_YES if the item we're about to download was, 
in fact, already downloaded once, and thus we provide a name for it,
+/** 
+ * 
+ * 
+ * @param tm which tree model are we inspecting
+ * @param iter location in the tree model we are getting data from
+ * @param finished_chain non-NULL for top-level call (for the item we're about 
to download), NULL otherwise
+ *   function sets it to #GNUNET_YES if the item we're about to download was, 
in fact, already downloaded once, and thus we provide a name for it,
  *   returning a finished relative filename that might only need .gnd appended 
to it, nothing else.
- * root_directory - top-level download directory to use. Set to the directory 
into which root of the tree (grand-*-parent item) was downloaded.
+ * @param root_directory top-level download directory to use. Set to the 
directory into which root of the tree (grand-*-parent item) was downloaded.
  *   If there's no already-downloaded grand-*-parents, set to default download 
directory (thus it will anways be filled on return).
- * relative_directory - name of the directory in which we're about to download 
a file, relative to the root_directory. Whether it includes name of the file 
itself, depends on finished_chain.
- * anonymity - anonymity level of one of the *parents. Initialize to -1. If 
none were downloaded, remains -1.
- * Returned strings should be freed with GNUNET_free() if not NULL.
- */
+ *    Returned strings should be freed with GNUNET_free() if not NULL.
+ * @param relative_directory name of the directory in which we're about to 
download a file, relative to the root_directory. Whether it includes name of 
the file itself, depends on finished_chain;
+ *    Returned strings should be freed with GNUNET_free() if not NULL.
+ * @param anonymity anonymity level of one of the *parents. Initialize to -1. 
If none were downloaded, remains -1.
+ */ 
 static void
 build_relative_name (GtkTreeModel *tm,
                     GtkTreeIter *iter,
@@ -672,10 +691,10 @@
 
 /**
  *
- * @param save_as - GNUNET_YES to open SaveAs dialog, GNUNET_NO to start 
downloading.
- * @param download_directly - GNUNET_YES to make SaveAs dialog initiate the 
download,
- *                     GNUNET_NO to only change names on the download panel.
- *                     Ingored if save_as is GNUNET_NO.
+ * @param save_as #GNUNET_YES to open SaveAs dialog, #GNUNET_NO to start 
downloading.
+ * @param download_directly #GNUNET_YES to make SaveAs dialog initiate the 
download,
+ *                     #GNUNET_NO to only change names on the download panel.
+ *                     Ingored if save_as is #GNUNET_NO.
  */
 static void
 start_download2 (int save_as, int download_directly)
@@ -776,7 +795,7 @@
 /**
  * "Download" was selected in the current search context menu.
  *
- * @param spc the 'struct SearchListPopupContext' of the menu
+ * @param spc the `struct SearchListPopupContext` of the menu
  * @param is_recursive was this the 'recursive' option?
  * @param save_as was this the 'save as' option?
  */
@@ -822,6 +841,7 @@
   start_download2 (GNUNET_NO, GNUNET_NO);
 }
 
+
 /**
  * User clicked on "..." button at the download options panel, next
  * to the Download As entry.
@@ -830,8 +850,8 @@
  * @param user_data the main window context
  */
 void
-GNUNET_GTK_search_frame_download_filename_change_button_clicked_cb (
-    GtkButton *button, gpointer user_data)
+GNUNET_GTK_search_frame_download_filename_change_button_clicked_cb (GtkButton 
*button, 
+                                                                   gpointer 
user_data)
 {
   start_download2 (GNUNET_YES, GNUNET_NO);
 }
@@ -841,7 +861,7 @@
  * "Download" was selected in the current search context menu.
  * 
  * @param item the 'download' menu item
- * @param user_data the 'struct SearchListPopupContext' of the menu 
+ * @param user_data the `struct SearchListPopupContext` of the menu 
  */
 static void
 start_download_ctx_menu (GtkMenuItem *item, gpointer user_data)
@@ -973,7 +993,7 @@
 /**
  * Called for each embedded sks. 
  *
- * @return GNUNET_OK to continue iteration
+ * @return #GNUNET_OK to continue iteration
  */
 typedef int (*EmbeddedSksCallback) (void *cls, 
                                      const struct GNUNET_FS_Uri *sks_uri,
@@ -992,7 +1012,14 @@
  * Metadata callback. Checks metadata item for being an SKS URI,
  * invokes the callback if so.
  *
- * @return GNUNET_OK if we did not invoke the callback, otherwise
+ * @param cls 
+ * @param plugin_name 
+ * @param type 
+ * @param format 
+ * @param data_mime_type 
+ * @param data 
+ * @param data_size 
+ * @return #GNUNET_OK if we did not invoke the callback, otherwise
  *         whatever the callback returned
  */
 static int
@@ -1040,7 +1067,11 @@
 
 
 /**
- * Search metadata for SKS URIs, invoke the callback for each one. 
+ * Search metadata for SKS URIs, invoke the callback for each one.  
+ * 
+ * @param meta 
+ * @param cb 
+ * @param cls 
  */
 static void
 find_embedded_sks (const struct GNUNET_CONTAINER_MetaData *meta, 
@@ -1066,6 +1097,13 @@
 /**
  * Called for every SKS URI in metadata. Adds up to 3 menu items
  * that will initiate downloads for these SKS URIs
+ * 
+ * @param cls 
+ * @param sks_uri 
+ * @param sks_uri_string 
+ * @param nsid 
+ * 
+ * @return 
  */
 static int
 populate_popup_with_sks_items (void *cls,
@@ -1391,12 +1429,12 @@
 
 
 /**
- * Copy all of the children of 'src_iter' from the 'src_model' to
- * become children of 'dst_iter' in the 'dst_model'.  The models are
+ * Copy all of the children of @a src_iter from the @a src_model to
+ * become children of @a dst_iter in the @a dst_model.  The models are
  * both 'GNUNET_GTK_file_sharing_result_tree_store' models.
  *
- * Note that we also need to update the 'struct SearchResult'
- * and (if it exists) the respective 'struct DownloadEntry'
+ * Note that we also need to update the `struct SearchResult`
+ * and (if it exists) the respective `struct DownloadEntry`
  * to refer to the new model.
  *
  * @param src_model source model
@@ -1961,7 +1999,7 @@
  *
  * @param tm tree model
  * @param iter parent of the subtree to check
- * @return GNUNET_YES if there are no active downloads left in the subtree
+ * @return #GNUNET_YES if there are no active downloads left in the subtree
  */
 static int
 stop_downloads_in_subtree (GtkTreeModel *tm,
@@ -2008,7 +2046,7 @@
  * the tab should be closed.
  *
  * @param button the button pressed by the user
- * @param user_data the 'struct SearchTab' of the respective tab to clean up
+ * @param user_data the `struct SearchTab` of the respective tab to clean up
  */
 void
 GNUNET_FS_GTK_search_result_clear_button_clicked (GtkButton * button, gpointer 
user_data)
@@ -2437,6 +2475,7 @@
   }
 }
 
+
 /**
  * We have received a search result from the FS API.  Add it to the
  * respective search tab.  The search result can be an 'inner'
@@ -2600,7 +2639,7 @@
 {
   struct SearchTab *ret;
 
-  ret = GNUNET_malloc (sizeof (struct SearchTab));
+  ret = GNUNET_new (struct SearchTab);
   ret->parent = parent;
   ret->sc = sc;
   ret->query_txt = parent->tab->query_txt;
@@ -3732,7 +3771,7 @@
  *         for this operation; should be set to NULL for
  *         SUSPEND and STOPPED events).  The value returned
  *         will be passed to future callbacks in the respective
- *         field in the GNUNET_FS_ProgressInfo struct.
+ *         field in the `struct GNUNET_FS_ProgressInfo`.
  */
 void *
 GNUNET_GTK_fs_event_handler (void *cls,