1 files changed, 52 insertions, 6 deletions

diff --git a/src/fs/gnunet-fs-gtk-event_handler.h b/src/fs/gnunet-fs-gtk-event_handler.h
index fcca7cef..310ba97c 100644
--- a/src/fs/gnunet-fs-gtk-event_handler.h
+++ b/src/fs/gnunet-fs-gtk-event_handler.h
@@ -26,6 +26,10 @@
 #include "gnunet-fs-gtk-common.h"
 
 
+/**
+ * State we keep for each (search) result entry in the
+ * tree view of a search tab.
+ */
 struct SearchResult;
 
 
@@ -54,31 +58,68 @@ struct SearchTab
    */
   struct GNUNET_FS_SearchContext *sc;
 
+  /**
+   * Text of the search query.
+   */
   char *query_txt;
 
+  /**
+   * GtkBuilder object for the search tab.
+   */ 
   GtkBuilder *builder;
 
+  /**
+   * Frame instance of the search tab.
+   */
   GtkWidget *frame;
 
+  /**
+   * The widget representing this search in the tab bar (not
+   * a GtkLabel, contains the actual label and the buttons).
+   */
   GtkWidget *tab_label;
 
+  /**
+   * Button to stop and close the search.
+   */
   GtkWidget *close_button;
 
+  /**
+   * Button to clear all entries for downloads that have completed.
+   */
   GtkWidget *clear_button;
 
+  /**
+   * Button to resume the search.
+   */
   GtkWidget *play_button;
 
+  /**
+   * Button to pause the search.
+   */
   GtkWidget *pause_button;
 
+  /**
+   * Textual label in the 'tab_label'
+   */
   GtkLabel *label;
 
+  /**
+   * Tree store with the search results.
+   */
   GtkTreeStore *ts;
 
+  /**
+   * Number of results we got for this search.
+   */
   unsigned int num_results;
 
 };
 
 
+/**
+ * Information we keep for each download.
+ */
 struct DownloadEntry
 {
 
@@ -156,14 +197,19 @@ GNUNET_GTK_add_to_uri_tab (GtkTreeIter * iter, struct SearchResult **sr,
 /**
  * Add a search result to the given search tab.
  *
- * @param tab search tab to extend
- * @param iter set to position where search result is added
- * @param parent_rr reference to parent entry in search tab
- * @param uri uri to add
+ * @param tab search tab to extend, never NULL
+ * @param iter set to position where search result is added (OUT only)
+ * @param parent_rr reference to parent entry in search tab, NULL for normal
+ *                  search results, 
+ * @param uri uri to add, can be NULL for top-level entry of a directory opened from disk
+ *                        (in this case, we don't know the URI and should probably not
+ *                         bother to calculate it)
  * @param meta metadata of the entry
- * @param result associated FS search result (can be NULL)
+ * @param result associated FS search result (can be NULL if this result
+ *                        was part of a directory)
  * @param applicability_rank how relevant is the result
- * @return entry for the search result
+ * @return struct representing the search result (also stored in the tree
+ *                model at 'iter')
  */
 struct SearchResult *
 GNUNET_GTK_add_search_result (struct SearchTab *tab, GtkTreeIter * iter,