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

[gnunet]

Author: LRN
Date: 2013-03-03 02:58:11 +0100 (Sun, 03 Mar 2013)
New Revision: 26267

Modified:
   gnunet-gtk/src/fs/gnunet-fs-gtk_namespace_organizer.c
   gnunet-gtk/src/fs/gnunet-fs-gtk_namespace_organizer.h
   gnunet-gtk/src/fs/gnunet-fs-gtk_publish-dialog.c
Log:
Documentation, minor fixes

Modified: gnunet-gtk/src/fs/gnunet-fs-gtk_namespace_organizer.c
===================================================================
--- gnunet-gtk/src/fs/gnunet-fs-gtk_namespace_organizer.c       2013-03-03 
01:58:05 UTC (rev 26266)
+++ gnunet-gtk/src/fs/gnunet-fs-gtk_namespace_organizer.c       2013-03-03 
01:58:11 UTC (rev 26267)
@@ -56,6 +56,16 @@
 #define GNUNET_GTK_MY_NAMESPACES_USE_THIS_COLUMN 3
 #define GNUNET_GTK_MY_NAMESPACES_ACTUAL_NAME_COLUMN 4
 
+/**
+ * User edited the name of a namespace.
+ * Rename the namespace, or queue the rename operation until
+ * key generation is finished for this namespace.
+ *
+ * @param renderer cell renderer
+ * @param path path to the cell that was edited (as a string)
+ * @param new_text new contents of the cell
+ * @param user_data context
+ */
 void
 GNUNET_GTK_namespace_organizer_namespaces_treeview_column_name_text_edited_cb (
     GtkCellRendererText *renderer, gchar *path, gchar *new_text,
@@ -135,6 +145,11 @@
   return FALSE;
 }
 
+/**
+ * Stops key generation.
+ *
+ * @param ctx NS organizer context
+ */
 static void
 stop_generation (struct GNUNET_GTK_NamespaceSelectorContext *ctx)
 {
@@ -147,6 +162,12 @@
   gtk_widget_set_visible (ctx->progress_label, FALSE);
 }
 
+/**
+ * Frees contents of the namespace list (the nsid values that are stored as
+ * untyped pointers in the tree).
+ *
+ * @param ctx NS organizer context
+ */
 static void
 free_lists_contents (struct GNUNET_GTK_NamespaceSelectorContext *ctx)
 {
@@ -175,6 +196,13 @@
   gtk_list_store_clear (ctx->my_ns_store);
 }
 
+/**
+ * Called when dialog is being closed (for any reason).
+ *
+ * @param dialog dialog being closed
+ * @param response_id identifies the event
+ * @param user_data context
+ */
 void
 GNUNET_GTK_namespace_organizer_dialog_response_cb (GtkDialog *dialog,
     gint response_id, gpointer user_data)
@@ -192,6 +220,12 @@
   }
 }
 
+/**
+ * Store a reference to the default namespace for later use.
+ *
+ * @param ctx context
+ * @param iter points to the default namespace in the list
+ */
 static void
 save_default_ns_reference (struct GNUNET_GTK_NamespaceSelectorContext *ctx, 
GtkTreeIter *iter)
 {
@@ -212,6 +246,12 @@
 }
 
 
+/**
+ * Try to mark an item in the list as the default namespace.
+ *
+ * @param ctx context
+ * @param iter points to the new default namespace in the list
+ */
 static void
 try_make_default (struct GNUNET_GTK_NamespaceSelectorContext *ctx, GtkTreeIter 
*toggled)
 {
@@ -322,6 +362,13 @@
     save_default_ns_reference (ctx, &my_iter);
 }
 
+/**
+ * Returns button visibility/sensitivity to normal.
+ *
+ * @param ctx context
+ * @param anything_selected TRUE if a namespace is selected in the list,
+ *                          FALSE otherwise
+ */
 static void
 set_normal_state (struct GNUNET_GTK_NamespaceSelectorContext *ctx, gboolean 
anything_selected)
 {
@@ -335,6 +382,12 @@
     gtk_widget_set_sensitive (ctx->create_button, TRUE);
 }
 
+/**
+ * Handles ns list selection changes.
+ *
+ * @param treeselection selection object
+ * @param user_data context
+ */
 static void
 my_ns_selection_changed (GtkTreeSelection *treeselection,
     gpointer user_data)
@@ -354,6 +407,12 @@
   set_normal_state (ctx, selected);
 }
 
+/**
+ * Opens the organizer dialog. Called from outside (by the main window).
+ *
+ * @param main_ctx context of the main window
+ * @return newly-created dialog window object
+ */
 GtkWindow *
 GNUNET_GTK_namespace_organizer_open (struct GNUNET_GTK_MainWindowContext 
*main_ctx)
 {
@@ -427,6 +486,14 @@
   return ctx->namespace_organizer;
 }
 
+/**
+ * Called when the organizer dialog is destoryed
+ * (happens at some point after it's closed).
+ * Cleans up references to the organizer dialog that main window stores.
+ *
+ * @param object the object that is being destroyed
+ * @param user_data main window context
+ */
 void
 GNUNET_GTK_namespace_organizer_dialog_destroy_cb (GtkWindow *object, gpointer 
user_data)
 {
@@ -438,6 +505,11 @@
   return;
 }
 
+/**
+ * Wrapper for GNUNET_GTK_namespace_organizer_open(), ensures that
+ * only one instance is opened.
+ * @param ctx main window context
+ */
 void
 GNUNET_GTK_open_ns_organizer (struct GNUNET_GTK_MainWindowContext *ctx)
 {
@@ -455,6 +527,13 @@
   ctx->ns_organizer_delete_handler_id = g_signal_connect (G_OBJECT 
(ctx->ns_organizer), "destroy", G_CALLBACK 
(GNUNET_GTK_namespace_organizer_dialog_destroy_cb), ctx);
 }
 
+/**
+ * Called when user clicks at 'Advertise namespace' button.
+ * Opens the advertising dialog (calls GNUNET_FS_GTK_advertise_namespace()).
+ *
+ * @param button button that was clicked
+ * @param user_data context
+ */
 void
 
GNUNET_GTK_namespace_organizer_namespaces_advertise_namespace_button_clicked_cb 
(
     GtkButton *button, gpointer user_data)
@@ -483,6 +562,14 @@
   g_free (name);
 }
 
+/**
+ * Called when user clicks at 'Do not delete' button.
+ * Returns the state back to normal (hides [un]confirmation buttons
+ * and the warning label).
+ *
+ * @param button button that was clicked
+ * @param user_data context
+ */
 void
 
GNUNET_GTK_namespace_organizer_namespaces_delete_namespace_unconfirmation_button_clicked_cb
 (
     GtkButton *button, gpointer user_data)
@@ -491,6 +578,16 @@
 }
 
 
+/**
+ * Called when user clicks at 'Do delete' button.
+ * Deletes selected namespace after double-checking that everything is
+ * in order.
+ * Returns the state back to normal (hides [un]confirmation buttons
+ * and the warning label).
+ *
+ * @param button button that was clicked
+ * @param user_data context
+ */
 void
 
GNUNET_GTK_namespace_organizer_namespaces_delete_namespace_confirmation_button_clicked_cb
 (
     GtkButton *button, gpointer user_data)
@@ -541,6 +638,7 @@
            * the namespace list right under us?).
            */
            /* TODO: display error message */
+          GNUNET_FS_namespace_delete (ns, GNUNET_NO);
         }
       }
       else
@@ -557,6 +655,13 @@
   set_normal_state (user_data, selected);
 }
 
+/**
+ * Called when user clicks at 'Delete' button.
+ * Shows the [un]confirmation buttons, as well as the warning.
+ *
+ * @param button button that was clicked
+ * @param user_data context
+ */
 void
 GNUNET_GTK_namespace_organizer_namespaces_delete_namespace_button_clicked_cb (
     GtkButton *button, gpointer user_data)
@@ -570,6 +675,11 @@
   gtk_widget_set_sensitive (ctx->create_button, FALSE);
 }
 
+/**
+ * Generates a random ns name.
+ *
+ * @return new name (free with GNUNET_free()).
+ */
 char *
 generate_local_ns_name ()
 {
@@ -591,6 +701,15 @@
 }
 
 
+/**
+ * Called when key generation for a namespace is finished.
+ * Hides the progress spinner, updates ns key hash, enables some buttons,
+ * does namespace renaming, if one was queued.
+ *
+ * @param cls context
+ * @param ns newly-created namespace (NULL on failure)
+ * @param emsg error message (NULL on success)
+ */
 static void
 ns_created (void *cls, struct GNUNET_FS_Namespace *ns, const char *emsg)
 {
@@ -667,6 +786,13 @@
 }
 
 
+/**
+ * Create a namespace.
+ * Adds a dummy to the list, starts the key generation process,
+ * shows the progress spinner, disables some buttons.
+ *
+ * @param ctx context
+ */
 static void
 create_namespace (struct GNUNET_GTK_NamespaceSelectorContext *ctx)
 {
@@ -716,6 +842,13 @@
     try_make_default (ctx, &my_iter);
 }
 
+/**
+ * Called when user clicks at 'Create' button.
+ * Creates a namespace.
+ *
+ * @param button button that was clicked
+ * @param user_data context
+ */
 void
 GNUNET_GTK_namespace_organizer_namespaces_create_namespace_button_clicked_cb (
     GtkButton *button, gpointer user_data)
@@ -723,6 +856,14 @@
   create_namespace (user_data);
 }
 
+/**
+ * Called when user toggles the radio button at a namespace in the list
+ * Tries to make that namespace the new default.
+ *
+ * @param cell_renderer renderer of the call that was toggled.
+ * @param path path to the cell that was toggled
+ * @param user_data context
+ */
 void
 
GNUNET_GTK_namespace_organizer_namespaces_treeview_column_usethis_toggle_toggled_cb
 (
     GtkCellRendererToggle *cell_renderer, gchar *path, gpointer user_data)
@@ -734,6 +875,13 @@
     try_make_default (ctx, &iter);
 }
 
+/**
+ * Called when user activates the appropriate item in main window `File' menu.
+ * Opens Namespace organizer dialog.
+ *
+ * @param menuitem item that was activated
+ * @param user_data main window context
+ */
 void
 GNUNET_GTK_main_menu_file_organize_namespaces_activate_cb (GtkMenuItem 
*menuitem,
     gpointer user_data)

Modified: gnunet-gtk/src/fs/gnunet-fs-gtk_namespace_organizer.h
===================================================================
--- gnunet-gtk/src/fs/gnunet-fs-gtk_namespace_organizer.h       2013-03-03 
01:58:05 UTC (rev 26266)
+++ gnunet-gtk/src/fs/gnunet-fs-gtk_namespace_organizer.h       2013-03-03 
01:58:11 UTC (rev 26267)
@@ -30,7 +30,7 @@
 #include "gnunet-fs-gtk.h"
 
 GtkObject *
-GNUNET_GTK_namespace_selector_open (struct GNUNET_GTK_MainWindowContext 
*main_ctx);
+GNUNET_GTK_namespace_organizer_open (struct GNUNET_GTK_MainWindowContext 
*main_ctx);
 
 #endif /* GNUNET_FS_GTK_NAMESPACE_ORGANIZER_H */
 /* end of gnunet-fs-gtk_namespace_organizer.c */

Modified: gnunet-gtk/src/fs/gnunet-fs-gtk_publish-dialog.c
===================================================================
--- gnunet-gtk/src/fs/gnunet-fs-gtk_publish-dialog.c    2013-03-03 01:58:05 UTC 
(rev 26266)
+++ gnunet-gtk/src/fs/gnunet-fs-gtk_publish-dialog.c    2013-03-03 01:58:11 UTC 
(rev 26267)
@@ -85,7 +85,7 @@
 
 
 /**
- * Columns in the pseudonym model.
+ * Columns in the identifiers model.
  */
 enum IDENTIFIERS_ModelColumns
   {
@@ -182,27 +182,95 @@
    */
   GtkWidget *edit_button;
 
+  /**
+   * Checkbox that enables/diables global namespace publication.
+   */
   GtkWidget *global_checkbox;
+
+  /**
+   * Checkbox that enables/diables private namespace publication.
+   */
   GtkWidget *own_checkbox;
+
+  /**
+   * The label that shows name of the default namespace (if no default
+   * namespace is selected, shows appropriate message).
+   */
   GtkWidget *own_label;
+
+  /**
+   * Treeview that shows previously-used identifiers and possible update IDs.
+   */
   GtkTreeView *identifiers_treeview;
+
+  /**
+   * Model of identifiers_treeview.
+   */
   GtkTreeModel *identifiers_treemodel;
+
+  /**
+   * Selection of identifiers_treeview.
+   */
   GtkTreeSelection *identifiers_selection;
+
+  /**
+   * Entry that allows users to specify the identifier.
+   */
   GtkWidget *identifier_entry;
+
+  /**
+   * Checkbox that enables/diables updateable private ns publications.
+   */
   GtkWidget *updateable_checkbox;
+
+  /**
+   * Entry that allows users to specify the update identifier.
+   */
   GtkWidget *update_id_entry;
 
+  /**
+   * VBox into which ns-related widgets are packed.
+   */
   GtkWidget *own_vbox;
+
+  /**
+   * HBox into which updateability-related widgets are packed.
+   */
   GtkWidget *update_id_hbox;
 
+  /**
+   * Name of the default namespace. May be NULL.
+   */
   gchar *ns_name;
+
+  /**
+   * Default namespace. May be NULL.
+   */
   struct GNUNET_FS_Namespace *ns;
 
+  /**
+   * Stores the value that was in identifier_entry previously.
+   */
   gchar *previous_id;
 
+  /**
+   * The top-level paned widget.
+   */
   GtkWidget *vpaned;
+
+  /**
+   * The frame that is packed at the bottom of vpaned.
+   */
   GtkWidget *bottom_frame;
+
+  /**
+   * Scrolled window into which identifiers_treeview is packed.
+   */
   GtkWidget *identifiers_scrolled;
+
+  /**
+   * Expander that controls identifiers_treeview visibility.
+   */
   GtkWidget *identifiers_expander;
 
   /**
@@ -633,6 +701,13 @@
   }
 }
 
+/**
+ * Called when global ns publication checkbox is toggled.
+ * Adjusts execute/cancel button sensitivity.
+ *
+ * @param togglebutton button that was toggled
+ * @param user_data context
+ */
 void
 GNUNET_GTK_master_publish_dialog_global_checkbox_toggled_cb (
     GtkToggleButton *togglebutton, gpointer user_data)
@@ -640,6 +715,13 @@
   update_selectivity_execute_cancel (user_data);
 }
 
+/**
+ * Called when private ns publication checkbox is toggled.
+ * Adjusts execute/cancel button sensitivity.
+ *
+ * @param togglebutton button that was toggled
+ * @param user_data context
+ */
 void
 GNUNET_GTK_master_publish_dialog_own_checkbox_toggled_cb (
     GtkToggleButton *togglebutton, gpointer user_data)
@@ -647,6 +729,13 @@
   update_selectivity_execute_cancel (user_data);
 }
 
+/**
+ * Called when updateability checkbox is toggled.
+ * Adjusts execute/cancel button sensitivity.
+ *
+ * @param togglebutton button that was toggled
+ * @param user_data context
+ */
 void
 GNUNET_GTK_master_publish_dialog_updateable_checkbox_toggled_cb (
     GtkToggleButton *togglebutton, gpointer user_data)
@@ -654,6 +743,12 @@
   update_selectivity_execute_cancel (user_data);
 }
 
+/**
+ * Generates an update id from a new id.
+ *
+ * @param new_text new id for which to generate update id.
+ * @return new update id (free with g_free ()).
+ */
 static gchar *
 generate_update_id (const gchar *new_text)
 {
@@ -683,6 +778,18 @@
   return new_update_id;
 }
 
+/**
+ * Checks whether existing update id was generated or not.
+ * Generates an update id from the previous id, then checks if
+ * it matches the one that is currently specified.
+ * If it does, then current update id was autogenerated.
+ *
+ * @param existing_update_id current update id
+ * @param previous_id previous value of the identifier, from which
+ *        current update id might have been generated
+ * @return TRUE if existing_update_id was generated from previous_id,
+ *         FALSE otherwise
+ */
 static gboolean
 update_id_is_autofilled (const gchar *existing_update_id, gchar *previous_id)
 {
@@ -695,6 +802,13 @@
   return result;
 }
 
+/**
+ * Generates a new update id and fills the entry, if necessary.
+ * Stores new identifier as previous_id in the context struct.
+ *
+ * @param ctx context
+ * @param new_text new identifier
+ */
 static void
 maybe_change_update_id (struct MainPublishingDialogContext *ctx,
     const gchar *new_text)
@@ -716,6 +830,14 @@
   ctx->previous_id = g_strdup (new_text);
 }
 
+/**
+ * Called when identifier entry contents are changed by anything.
+ * Generates a new update id and fills the entry, if necessary.
+ * Updates execute/cancel buttons sensitivity.
+ *
+ * @param widget the entry that was changed
+ * @param user_data context
+ */
 void
 GNUNET_GTK_master_publish_dialog_identifier_entry_changed_cb (
     GtkWidget *widget, gpointer user_data)
@@ -734,7 +856,8 @@
 
 /**
  * The selection in the identifier tree view changed.
- * Update copy text into identifier entry.
+ * Copy text into identifier entry, or
+ * adjust selection, if selected item is a clone.
  *
  * @param ts the changed selection
  * @param user_data master publishing dialog context of our window
@@ -1089,6 +1212,7 @@
 
 /**
  * Close the progress dialog and free its handle.
+ * Updates all buttons sensitivity.
  *
  * @param adcc context for the progress dialog to close
  */
@@ -2042,7 +2166,7 @@
 
 
 /**
- * Remove all of the keywords from the file information in the tree store
+ * Remove all of the keywords from the file information item in the tree store
  *
  * @param tm tree model / store
  * @param iter current position in the recursion
@@ -2070,6 +2194,11 @@
   }
 }
 
+/**
+ * Remove all of the keywords from all file information structs in the tree 
store
+ *
+ * @param ctx context
+ */
 static void
 clear_keywords_from_tm (struct MainPublishingDialogContext *ctx)
 {
@@ -2136,6 +2265,16 @@
   return FALSE;
 }
 
+/**
+ * Called when expander changes its state (expanded/hidden).
+ * Hides the widget, adjusts the paned position to compensate,
+ * changes resizability of the bottom frame (it will not get any
+ * extra space while its only resizable widget is hidden).
+ *
+ * @param object expander
+ * @param param_spec parameter that was changed
+ * @param user_data context
+ */
 static void
 expander_callback (GObject    *object,
                    GParamSpec *param_spec,
@@ -2349,6 +2488,15 @@
 }
 
 
+/**
+ * Called by a hashmap iterator.
+ * Frees its argument with GNUNET_free ().
+ *
+ * @param cls closure
+ * @param key key from the map
+ * @param value value from the map
+ * @return GNUNET_YES, always.
+ */
 static int
 free_seen_paths (void *cls, const struct GNUNET_HashCode * key, void *value)
 {