add some comments

gui.c

@@ -35,10 +35,17 @@ typedef struct {
     gint x;               /* combo box item number */
 } WidgetListElem;
 
-static GtkKnobAnim *knob_anim = NULL;
+static GtkKnobAnim *knob_anim = NULL; /* animation used by knobs */
 static GList *widget_list = NULL;     /* this list contains WidgetListElem data elements */
-static gboolean allow_send = FALSE;
+static gboolean allow_send = FALSE;   /* if FALSE GUI parameter changes won't be sent to device */
 
+/**
+ *  show_error_message:
+ *  @parent: transient parent, or NULL for none
+ *  @message: error description
+ *
+ *  Shows error message dialog.
+ **/
 void show_error_message(GtkWidget *parent, gchar *message)
 {
     g_return_if_fail(message != NULL);
@@ -53,6 +60,13 @@ void show_error_message(GtkWidget *parent, gchar *message)
     gtk_widget_destroy(msg);
 }
 
+/**
+ *  value_changed_option_cb:
+ *  @adj: the object which emitted the signal
+ *  @setting: setting controlled by adj
+ *
+ *  Sets effect value.
+ **/
 void value_changed_option_cb(GtkAdjustment *adj, EffectSettings *setting)
 {
     g_return_if_fail(setting != NULL);
@@ -78,6 +92,13 @@ void value_changed_option_cb(GtkAdjustment *adj, EffectSettings *setting)
     }
 }
 
+/**
+ *  toggled_cb:
+ *  @button: the object which emitted the signal
+ *  @effect: effect controlled by button
+ *
+ *  Turns effect on/off basing on state of button.
+ **/
 void toggled_cb(GtkToggleButton *button, Effect *effect)
 {
     g_return_if_fail(effect != NULL);
@@ -88,6 +109,16 @@ void toggled_cb(GtkToggleButton *button, Effect *effect)
     }
 }
 
+/**
+ *  widget_list_add:
+ *  @widget: GtkObject to add to widget list
+ *  @id: object controlled ID
+ *  @position: object controlled position
+ *  @value: effect value type (if widget is GtkComboBox, otherwise -1)
+ *  @x: combo box item number (if widget is GtkComboBox, otherwise -1)
+ *
+ *  Adds widget to widget list.
+ **/
 static void widget_list_add(GtkObject *widget, gint id, gint position, gint value, gint x)
 {
     WidgetListElem *el;
@@ -102,6 +133,13 @@ static void widget_list_add(GtkObject *widget, gint id, gint position, gint valu
     widget_list = g_list_prepend(widget_list, el);
 }
 
+/**
+ *  apply_widget_setting:
+ *  @el: widget list element
+ *  @param: parameter to set
+ *
+ *  Sets widget list element value to param value.
+ **/
 static void apply_widget_setting(WidgetListElem *el, SettingParam *param)
 {
     if ((el->id == param->id) && (el->position == param->position)) {
@@ -117,6 +155,12 @@ static void apply_widget_setting(WidgetListElem *el, SettingParam *param)
     }
 }
 
+/**
+ *  apply_preset_to_gui:
+ *  @preset: preset to sync
+ *
+ *  Synces GUI with preset.
+ **/
 static void apply_preset_to_gui(Preset *preset)
 {
     g_return_if_fail(preset != NULL);
@@ -136,6 +180,11 @@ static void apply_preset_to_gui(Preset *preset)
     allow_send = TRUE;
 }
 
+/**
+ *  apply_current_preset:
+ *
+ *  Synces GUI with device current edit buffer.
+ **/
 static void apply_current_preset()
 {
     GString *msg = get_current_preset();
@@ -145,6 +194,15 @@ static void apply_current_preset()
     preset_free(preset);
 }
 
+/**
+ *  create_table:
+ *  @settings: effect parameters
+ *  @amt: amount of effect parameters
+ *
+ *  Creates knobs that allow user to set effect parameters.
+ *
+ *  Return value: GtkTable containing necessary widgets to set effect parameters.
+ **/
 GtkWidget *create_table(EffectSettings *settings, gint amt)
 {
     GtkWidget *table, *label, *widget, *knob;
@@ -181,6 +239,14 @@ GtkWidget *create_table(EffectSettings *settings, gint amt)
     return table;
 }
 
+/**
+ *  create_on_off_button:
+ *  @effect: Effect that can be turned on/off
+ *
+ *  Creates toggle button that allow user to turn effect on/off.
+ *
+ *  Return value: GtkToggleButton
+ **/
 GtkWidget *create_on_off_button(Effect *effect)
 {
     GtkWidget *button = gtk_toggle_button_new_with_label(effect->label);
@@ -197,6 +263,12 @@ typedef struct {
     GtkWidget *child;      /* child widget */
 } EffectSettingsGroup;
 
+/**
+ *  effect_settings_group_free:
+ *  @group: group to be freed
+ *
+ *  Frees all memory used by group
+ **/
 void effect_settings_group_free(EffectSettingsGroup *group)
 {
     /* destroy widget without parent */
@@ -207,6 +279,13 @@ void effect_settings_group_free(EffectSettingsGroup *group)
     g_free(group);
 }
 
+/**
+ *  combo_box_changed_cb:
+ *  @widget: the object which emitted the signal
+ *  @data: user data (unused, can be anything)
+ *
+ *  Switches effect type and shows widgets allowing to set selected effect type parameters.
+ **/
 void combo_box_changed_cb(GtkComboBox *widget, gpointer data)
 {
     GtkWidget *child;
@@ -236,6 +315,15 @@ void combo_box_changed_cb(GtkComboBox *widget, gpointer data)
     }
 }
 
+/**
+ *  create_widget_container:
+ *  @group: Effect type groups
+ *  @amt: amount of effect groups
+ *
+ *  Creates widget allowing user to choose effect type.
+ *
+ *  Return value: widget that allow user to set effect type.
+ **/
 GtkWidget *create_widget_container(EffectGroup *group, gint amt)
 {
     GtkWidget *vbox;
@@ -281,6 +369,15 @@ GtkWidget *create_widget_container(EffectGroup *group, gint amt)
     return vbox;
 }
 
+/**
+ *  create_vbox:
+ *  @widgets: Effect descriptions
+ *  @amt: amount of effect descriptions
+ *
+ *  Creates vbox containing widgets allowing user to set effect options.
+ *
+ *  Return value: widget that allow user to set effect options.
+ **/
 GtkWidget *create_vbox(Effect *widgets, gint amt)
 {
     GtkWidget *vbox;
@@ -313,6 +410,15 @@ enum {
   NUM_COLUMNS
 };
 
+/**
+ *  row_activate_cb:
+ *  @treeview: the object which emitted the signal
+ *  @path: the GtkTreePath for the activated row
+ *  @column: the GtkTreeViewColumn in which the activation occurred
+ *  @model: model holding preset names
+ *
+ *  Sets active device preset to preset selected by user.
+ **/
 void row_activate_cb(GtkTreeView *treeview, GtkTreePath *path, GtkTreeViewColumn *column, GtkTreeModel *model) {
     GtkTreeIter iter;
     gint id;
@@ -327,6 +433,14 @@ void row_activate_cb(GtkTreeView *treeview, GtkTreePath *path, GtkTreeViewColumn
     }
 }
 
+/**
+ *  fill_store_with_presets:
+ *  @model: model to fill
+ *  @bank: preset bank
+ *  @name: preset bank description visible to user
+ *
+ *  Appends to model preset names found in device preset bank.
+ **/
 static void fill_store_with_presets(GtkTreeStore *model, guint bank, gchar *name)
 {
     GtkTreeIter iter;
@@ -354,12 +468,25 @@ static void fill_store_with_presets(GtkTreeStore *model, guint bank, gchar *name
     g_strfreev(presets);
 }
 
+/**
+ *  fill_store:
+ *  @model: model to fill
+ *
+ *  Fills model with preset names found on device.
+ **/
 static void fill_store(GtkTreeStore *model)
 {
     fill_store_with_presets(model, PRESETS_USER, "User Presets");
     fill_store_with_presets(model, PRESETS_SYSTEM, "System Presets");
 }
 
+/**
+ *  create_preset_tree:
+ *
+ *  Creates treeview showing list of presets available on device.
+ *
+ *  Return value: treeview containing all preset names found on device.
+ **/
 GtkWidget *create_preset_tree()
 {
     GtkWidget *treeview;
@@ -385,6 +512,13 @@ GtkWidget *create_preset_tree()
     return treeview;
 }
 
+/**
+ *  show_store_preset_window:
+ *  @window: application toplevel window
+ *  @default_name: default preset name
+ *
+ *  Shows window allowing user to store current edit buffer.
+ **/
 static void show_store_preset_window(GtkWidget *window, gchar *default_name)
 {
     GtkWidget *dialog, *cmbox, *entry, *table, *label;
@@ -433,12 +567,24 @@ static void show_store_preset_window(GtkWidget *window, gchar *default_name)
     gtk_widget_destroy(dialog);
 }
 
+/**
+ *  action_store_cb:
+ *  @action: the object which emitted the signal
+ *
+ *  Shows store preset window.
+ **/
 static void action_store_cb(GtkAction *action)
 {
     GtkWidget *window = g_object_get_data(G_OBJECT(action), "window");
     show_store_preset_window(window, NULL);
 }
 
+/**
+ *  action_show_about_dialog_cb:
+ *  @action: the object which emitted the signal
+ *
+ *  Shows about dialog.
+ **/
 static void action_show_about_dialog_cb(GtkAction *action)
 {
     static const gchar * const authors[] = {
@@ -467,6 +613,13 @@ static SupportedFileTypes file_types[] = {
 };
 static guint n_file_types = G_N_ELEMENTS(file_types);
 
+/**
+ *  action_open_preset_cb:
+ *  @action: the object which emitted the signal
+ *
+ *  Shows file chooser dialog.
+ *  If user opens valid preset file, the preset gets applied to edit buffer and store preset window is shown.
+ **/
 static void action_open_preset_cb(GtkAction *action)
 {
     static GtkWidget *dialog = NULL;
@@ -552,6 +705,12 @@ static void action_open_preset_cb(GtkAction *action)
     dialog = NULL;
 }
 
+/**
+ *  widget_list_free:
+ *  @list: widget list to be freed
+ *
+ *  Frees all memory used by widget list.
+ */
 static void widget_list_free(GList *list)
 {
     GList *iter;
@@ -561,6 +720,12 @@ static void widget_list_free(GList *list)
     g_list_free(list);
 }
 
+/**
+ *  action_quit_cb:
+ *  @action: the object which emitted the signal
+ *
+ *  Destroys action object "window" data, then stops gtk main loop.
+ **/
 static void action_quit_cb(GtkAction *action)
 {
     GtkWidget *window = g_object_get_data(G_OBJECT(action), "window");
@@ -597,14 +762,31 @@ static const gchar *menu_info =
 " </menubar>"
 "</ui>";
 
+/**
+ *  add_action_data:
+ *  @ui: GtkUIManager to lookup actions
+ *  @path: path to action
+ *  @window: toplevel window
+ *
+ *  Sets action object "window" data to toplevel window.
+ **/
 static void add_action_data(GtkUIManager *ui, const gchar *path, GtkWidget *window)
 {
     GtkAction *action;
 
     action = gtk_ui_manager_get_action(ui, path);
+    g_return_if_fail(action != NULL);
+
     g_object_set_data(G_OBJECT(action), "window", window);
 }
 
+/**
+ *  add_menubar:
+ *  @window: toplevel window
+ *  @vbox: vbox to hold menubar
+ *
+ *  Creates menubar (adds accel group to toplevel window as well) and packs it into vbox.
+ **/
 static void add_menubar(GtkWidget *window, GtkWidget *vbox)
 {
     GtkUIManager *ui;
@@ -636,6 +818,11 @@ static void add_menubar(GtkWidget *window, GtkWidget *vbox)
     g_object_unref(ui);
 }
 
+/**
+ *  gui_create:
+ *
+ *  Creates main window.
+ **/
 void gui_create()
 {
     GtkWidget *window;
@@ -683,6 +870,11 @@ void gui_create()
     g_signal_connect(G_OBJECT(window), "delete_event", G_CALLBACK(gtk_main_quit), NULL);
 }
 
+/**
+ *  gui_free:
+ *
+ *  Frees memory allocated by gui_create which is not explicitly freed when main window is destroyed.
+ **/
 void gui_free()
 {
     widget_list_free(widget_list);

preset.c

@@ -112,10 +112,14 @@ static void XMLCALL text_cb(void *data, const char* text, int len)
     g_free(value);
 }
 
-/*
+/**
-   Parses preset file
+ *  create_preset_from_xml_file:
-   On success returns Preset which must be freed using preset_free, or NULL on error
+ *  @filename: valid path to file
-*/
+ *
+ *  Tries to open file pointed by path, then parses it.
+ *
+ *  Return value: Preset which must be freed using preset_free, or NULL on error.
+ **/
 Preset *create_preset_from_xml_file(gchar *filename)
 {
     GFile *file;
@@ -165,6 +169,14 @@ Preset *create_preset_from_xml_file(gchar *filename)
     return preset;
 }
 
+/**
+ *  create_preset_from_data:
+ *  @data: unpacked RECEIVE_PRESET_PARAMETERS message
+ *
+ *  Parses message
+ *
+ *  Return value: Preset which must be freed using preset_free, or NULL on error.
+ **/
 Preset *create_preset_from_data(GString *data)
 {
     gint total;
@@ -213,6 +225,12 @@ Preset *create_preset_from_data(GString *data)
     return preset;
 }
 
+/**
+ *  preset_free:
+ *  @preset: preset to be freed
+ *
+ *  Frees all memory used by preset
+ **/
 void preset_free(Preset *preset)
 {
     g_return_if_fail(preset != NULL);