add comments

TODO

@@ -3,3 +3,4 @@
 -handling presets (saving, exporting to xml patches)
 -buildsystem (install knob.png to share dir, don't use inline knob pixbuf)
 -add expression pedal settings to gui
+-read asynchronously from MIDI IN

effects.c

@@ -735,7 +735,7 @@ EffectList effects[] = {
 int n_effects = G_N_ELEMENTS(effects);
 
 typedef struct {
-    const gchar *label;
+    gchar *label;
     guint id;
     guint position;
     EffectValues *values;
@@ -879,8 +879,14 @@ static Modifier modifiers[] = {
 
 int n_modifiers = G_N_ELEMENTS(modifiers);
 
-/*
+/**
-    returned value must not be freed
+ *  get_modifier:
+ *  @id: modifier ID
+ *  @position: modifier position
+ *
+ *  Gets modifier info.
+ *
+ *  Return value: Modifier which must not be freed, or NULL if no matching Modifier has been found.
 */
 static Modifier *get_modifier(guint id, guint position)
 {
@@ -893,6 +899,14 @@ static Modifier *get_modifier(guint id, guint position)
     return NULL;
 }
 
+/**
+ *  get_modifier_settings:
+ *  @values: possible setting values
+ *
+ *  Creates EffectSettings containing expression pedal min and max settings.
+ *
+ *  Return value: EffectSettings which must be freed using effect_settings_free.
+ **/
 static EffectSettings *get_modifier_settings(EffectValues *values)
 {
     if (values == NULL)
@@ -913,6 +927,24 @@ static EffectSettings *get_modifier_settings(EffectValues *values)
     return settings;
 }
 
+/**
+ *  effect_settings_free:
+ *  @settings: settings to be freed
+ *
+ *  Frees all memory used by EffectSettings.
+ **/
+static void effect_settings_free(EffectSettings *settings)
+{
+    g_slice_free1(2 * sizeof(EffectSettings), settings);
+}
+
+/**
+ *  modifier_linkable_list:
+ *
+ *  Retrieves modifier linkable gruop from device.
+ *
+ *  Return value: ModifierGroup which must be freed using modifier_group_free.
+ **/
 ModifierGroup *modifier_linkable_list()
 {
     guint group_id;
@@ -963,6 +995,12 @@ ModifierGroup *modifier_linkable_list()
     return modifier_group;
 }
 
+/**
+ *  modifier_group_free:
+ *  @modifier_group: group to be freed
+ *
+ *  Frees all memory used by ModifierGroup.
+ **/
 void modifier_group_free(ModifierGroup *modifier_group)
 {
     g_return_if_fail(modifier_group != NULL);
@@ -970,8 +1008,7 @@ void modifier_group_free(ModifierGroup *modifier_group)
     int x;
     for (x=0; x<modifier_group->group_amt; x++) {
         if (modifier_group->group[x].settings)
-            g_slice_free1(2 * sizeof(EffectSettings),
+            effect_settings_free(modifier_group->group[x].settings);
-                          modifier_group->group[x].settings);
     }
     g_slice_free1(modifier_group->group_amt * sizeof(EffectGroup),
                   modifier_group->group);

effects.h

@@ -26,7 +26,7 @@ typedef struct {
 } EffectValues;
 
 typedef struct {
-    char *label;          /* Parameter name */
+    gchar *label;         /* Parameter name */
     guint id;             /* ID (to set parameter) */
     guint position;       /* position */
     EffectValues *values; /* valid parameter values */
@@ -42,7 +42,7 @@ typedef struct {
 } EffectGroup;
 
 typedef struct {
-    char *label;        /* Base effect name */
+    gchar *label;       /* Base effect name */
     guint id;           /* ID (to set effect on/off) */
     guint position;     /* position */
     EffectGroup *group; /* possible effect types */

gdigi.c

@@ -51,10 +51,13 @@ static char calculate_checksum(gchar *array, gint length)
     return checksum;
 }
 
-/*
+/**
-   opens MIDI device
+ *  open_device:
-   Returns TRUE on error
+ *
-*/
+ *  Opens MIDI device. This function modifies global input and output variables.
+ *
+ *  Return value: FALSE on success, TRUE on error.
+ **/
 gboolean open_device()
 {
     int err;
@@ -76,14 +79,27 @@ gboolean open_device()
     return FALSE;
 }
 
+/**
+ *  send_data:
+ *  @data: data to be sent
+ *  @length: data length
+ *
+ *  Sends data to device. This function uses global output variable.
+ **/
 void send_data(char *data, int length)
 {
-    if (output == NULL)
-        open_device();
-
     snd_rawmidi_write(output, data, length);
 }
 
+/**
+ *  pack_data:
+ *  @data: data to be packed
+ *  @len: data length
+ *
+ *  Packs data using method used on all newer DigiTech products.
+ *
+ *  Return value: GString containing packed data
+ **/
 GString *pack_data(gchar *data, gint len)
 {
     GString *packed;
@@ -114,6 +130,12 @@ GString *pack_data(gchar *data, gint len)
     return packed;
 }
 
+/**
+ *  unpack_message:
+ *  @msg: message to unpack
+ *
+ *  Unpacks message data. This function modifies given GString.
+ **/
 static void unpack_message(GString *msg)
 {
     int offset;
@@ -152,11 +174,13 @@ static void unpack_message(GString *msg)
     g_string_truncate(msg, i);
 }
 
-/*
+/**
-   reads data from MIDI IN
+ *  read_data:
-   returns GString containing data
+ *
-   if no data was read it returns NULL
+ *  Reads data from MIDI IN. This function uses global input variable.
-*/
+ *
+ *  Return value: GString containing data, or NULL when no data was read.
+ **/
 GString* read_data()
 {
     /* This is mostly taken straight from alsa-utils-1.0.19 amidi/amidi.c
@@ -220,19 +244,14 @@ GString* read_data()
     return string;
 }
 
-static void clear_midi_in_buffer()
+/**
-{
+ *  send_message:
-    GString *str;
+ *  @procedure: procedure ID
-
+ *  @data: unpacked message data
-    do {
+ *  @len: data length
-        str = read_data();
+ *
-    } while (str != NULL);
+ *  Creates SysEx message then sends it. This function uses folowing global variables: device_id, family_id and product_id.
-}
+ **/
-
-/*
-   data - unpacked data to send
-   len  - data length
-*/
 void send_message(gint procedure, gchar *data, gint len)
 {
     GString *msg = g_string_new_len("\xF0"          /* SysEx status byte */
@@ -258,8 +277,17 @@ void send_message(gint procedure, gchar *data, gint len)
     g_string_free(msg, TRUE);
 }
 
-static gint get_message_id(GString *msg)
+/**
+ *  get_message_id:
+ *  @msg: SysEx message
+ *
+ *  Checks message ID.
+ *
+ *  Return value: MessageID, or -1 on error.
+ **/
+static MessageID get_message_id(GString *msg)
 {
+    /* TODO: sanity checks */
     g_return_val_if_fail(msg != NULL, -1);
 
     if (msg->len > 7) {
@@ -268,6 +296,14 @@ static gint get_message_id(GString *msg)
     return -1;
 }
 
+/**
+ *  get_message_by_id:
+ *  @id: MessageID of requested message
+ *
+ *  Reads data from MIDI IN until message with matching id is found.
+ *
+ *  Return value: GString containing unpacked message.
+ **/
 GString *get_message_by_id(MessageID id)
 {
     GString *data = NULL;
@@ -283,6 +319,13 @@ GString *get_message_by_id(MessageID id)
     return data;
 }
 
+/**
+ *  append_value:
+ *  @msg: message to append value
+ *  @value: value to append
+ *
+ *  Packs value using scheme used on all newer DigiTech products.
+ **/
 void append_value(GString *msg, guint value)
 {
     /* check how many bytes long the value is */
@@ -310,11 +353,14 @@ void append_value(GString *msg, guint value)
     }
 }
 
-/*
+/**
-   id - ID as found in preset file
+ *  set_option:
-   position - Position as found in preset file
+ *  @id: Parameter ID
-   value - Value as found in preset file
+ *  @position: Parameter position
-*/
+ *  @value: Parameter value
+ *
+ *  Forms SysEx message to set parameter then sends it to device.
+ **/
 void set_option(guint id, guint position, guint value)
 {
     GString *msg = g_string_sized_new(9);
@@ -326,7 +372,13 @@ void set_option(guint id, guint position, guint value)
     g_string_free(msg, TRUE);
 }
 
-/* x = 0 to 60 */
+/**
+ *  switch_preset:
+ *  @bank: preset bank
+ *  @x: preset index
+ *
+ *  Switches to selected preset.
+ **/
 void switch_preset(guint bank, guint x)
 {
     GString *msg = g_string_sized_new(6);
@@ -339,12 +391,13 @@ void switch_preset(guint bank, guint x)
     g_string_free(msg, TRUE);
 }
 
-/* level = 0 to 99 */
+/**
-void set_preset_level(int level)
+ *  store_preset_name:
-{
+ *  @x: preset index
-    set_option(PRESET_LEVEL, PRESET_POSITION, level);
+ *  @name: preset name
-}
+ *
-
+ *  Stores current edit buffer in user presets bank.
+ **/
 void store_preset_name(int x, const gchar *name)
 {
     GString *msg = g_string_sized_new(6);
@@ -357,7 +410,13 @@ void store_preset_name(int x, const gchar *name)
     g_string_free(msg, TRUE);
 }
 
-/* x = 0 to 59 (preset number) */
+/**
+ *  set_preset_name:
+ *  @x: preset index
+ *  @name: preset name
+ *
+ *  Sets preset name.
+ **/
 void set_preset_name(int x, gchar *name)
 {
     GString *msg = g_string_sized_new(12);
@@ -369,12 +428,14 @@ void set_preset_name(int x, gchar *name)
     g_string_free(msg, TRUE);
 }
 
-/*
+/**
-    Queries user preset names
+ *  query_preset_names:
-    Valid bank values are PRESETS_SYSTEM and PRESETS_USER
+ *  @bank: preset bank
-    Returns GStrv which must be freed with g_strfreev
+ *
-    Returns NULL on error
+ *  Queries preset names.
-*/
+ *
+ *  Return value: GStrv which must be freed with g_strfreev, or NULL on error.
+ **/
 GStrv query_preset_names(gchar bank)
 {
     GString *data = NULL;
@@ -383,9 +444,6 @@ GStrv query_preset_names(gchar bank)
     int n_total;              /* total number of presets */
     gchar **str_array = NULL;
 
-    /* clear MIDI IN buffer */
-    clear_midi_in_buffer();
-
     /* query user preset names */
     send_message(REQUEST_PRESET_NAMES, &bank, 1);
 
@@ -412,13 +470,17 @@ GStrv query_preset_names(gchar bank)
     return str_array;
 }
 
+/**
+ *  get_current_preset:
+ *
+ *  Queries current edit buffer.
+ *
+ *  Return value: GString containing RECEIVE_PRESET_PARAMETERS SysEx message.
+ **/
 GString *get_current_preset()
 {
     GString *data = NULL;
 
-    /* clear MIDI IN buffer */
-    clear_midi_in_buffer();
-
     send_message(REQUEST_PRESET, "\x04\x00", 3);
 
     /* read reply */
@@ -427,6 +489,16 @@ GString *get_current_preset()
     return data;
 }
 
+/**
+ *  request_who_am_i:
+ *  @device_id: Variable to hold device ID
+ *  @family_id: Variable to hold family ID
+ *  @product_id: Variable to hold product ID
+ *
+ *  Requests device information.
+ *
+ *  Return value: TRUE on success, FALSE on error.
+ **/
 static gboolean request_who_am_i(unsigned char *device_id, unsigned char *family_id,
                                  unsigned char *product_id)
 {

gdigi.h

@@ -539,7 +539,7 @@ enum {
 #define USB_AUDIO_PLAYBACK_MIX 12297
 #define USB_AUDIO_LEVEL 12307
 
-enum {
+typedef enum {
     PRESETS_SYSTEM = 0,
     PRESETS_USER = 1,
     PRESETS_ARTIST = 2,
@@ -551,7 +551,7 @@ enum {
 
     /* Version 2 and later */
     PRESETS_EXTERNAL = 6
-};
+} PresetBank;
 
 typedef enum {
     REQUEST_WHO_AM_I = 0x01,

tests.c

@@ -210,9 +210,6 @@ void test_presets()
 
     for (x=0; x<=60; x++)
         switch_preset(PRESETS_SYSTEM, x);
-
-    for (x=0; x<=99; x++)
-        set_preset_level(x);
 }
 
 void test_pickups()