[Xfce4-commits] <parole:master> Comments for parole-builder and parole-button.

[Sean Davis]

Updating branch refs/heads/master
         to 95845ec562460427bf0edb82e88bfa5a2764396a (commit)
       from ca1d697e6a62f49002ab8e6d1a0302b938709072 (commit)

commit 95845ec562460427bf0edb82e88bfa5a2764396a
Author: Sean Davis <smd.seandavis at gmail.com>
Date:   Tue Nov 13 06:09:12 2012 -0500

    Comments for parole-builder and parole-button.

 src/parole-builder.c |   20 ++++++++++++----
 src/parole-button.c  |   63 +++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 77 insertions(+), 6 deletions(-)

diff --git a/src/parole-builder.c b/src/parole-builder.c
index d874948..5598683 100644
--- a/src/parole-builder.c
+++ b/src/parole-builder.c
@@ -32,7 +32,11 @@
 #include "parole-builder.h"
 
 
-/* Build Parole's UI from the interface-file */
+/**
+ * parole_builder_get_main_interface:
+ * 
+ * Build Parole's UI from the interface-file.
+ **/
 GtkBuilder *
 parole_builder_get_main_interface (void)
 {
@@ -51,16 +55,22 @@ parole_builder_get_main_interface (void)
     return GTK_BUILDER (parole_builder_object);
 }
 
-GtkBuilder *parole_builder_new_from_string (const gchar *ui, gsize length)
+/**
+ * parole_builder_new_from_string:
+ * @ui     : the string containing parole's condensed glade interface.
+ * @length : the length of the ui string.
+ *
+ * Build Parole's UI from the condensed glade string.
+ **/
+GtkBuilder *
+parole_builder_new_from_string (const gchar *ui, gsize length)
 {
     GError *error = NULL;
     GtkBuilder *builder;
     
     builder = gtk_builder_new ();
 
-    /*
-     * Set the locale before loading the GtkBuilder interface definition
-     */
+    /* Set the locale before loading the GtkBuilder interface definition. */
     xfce_textdomain (GETTEXT_PACKAGE, LOCALEDIR, "UTF-8");
     
     gtk_builder_add_from_string (builder, ui, length, &error);
diff --git a/src/parole-button.c b/src/parole-button.c
index 2ddf2a9..4023396 100644
--- a/src/parole-button.c
+++ b/src/parole-button.c
@@ -79,6 +79,12 @@ static guint signals[LAST_SIGNAL] = { 0 };
 
 G_DEFINE_TYPE(ParoleButton, parole_button, G_TYPE_OBJECT)
 
+/**
+ * parole_button_get_key:
+ * @keycode : an #int representing a key on a keyboard.
+ *
+ * Check if the pressed key is mapped to a function in Parole.
+ **/
 static guint
 parole_button_get_key (unsigned int keycode)
 {
@@ -95,6 +101,14 @@ parole_button_get_key (unsigned int keycode)
     return key;
 }
 
+/**
+ * parole_button_filter_x_events:
+ * @xevent : a #GdkXEvent to filter.
+ * @ev     : the #GdkEvent passed by the callback function.
+ * @data   : user-data passed by the callback function.
+ *
+ * Filter X events for keypresses, and pass the keypresses on to be processed.
+ **/
 static GdkFilterReturn
 parole_button_filter_x_events (GdkXEvent *xevent, GdkEvent *ev, gpointer data)
 {
@@ -121,6 +135,15 @@ parole_button_filter_x_events (GdkXEvent *xevent, GdkEvent *ev, gpointer data)
     return GDK_FILTER_CONTINUE;
 }
 
+/**
+ * parole_button_grab_keystring:
+ * @button  : the #ParoleButton instance to handle keypresses.
+ * @keycode : the #int representing the pressed key on the keyboard.
+ *
+ * Attempt to get the pressed key and modifier keys.
+ * 
+ * Return value: %TRUE on success, else %FALSE.
+ **/ 
 static gboolean
 parole_button_grab_keystring (ParoleButton *button, guint keycode)
 {
@@ -159,7 +182,16 @@ parole_button_grab_keystring (ParoleButton *button, guint keycode)
     return TRUE;
 }
 
-
+/**
+ * parole_button_xevent_key:
+ * @button : the #ParoleButton instance to handle keypresses.
+ * @keysym : an #int representing the keysym to be converted to a keycode.
+ * @key    : the #ParoleButtonKey that represents the pressed key.
+ *
+ * Attempt to map the key and keycode to the parole_key_map.
+ *
+ * Return value: %TRUE on success, else %FALSE.
+ **/
 static gboolean
 parole_button_xevent_key (ParoleButton *button, guint keysym , ParoleButtonKey key)
 {
@@ -185,6 +217,12 @@ parole_button_xevent_key (ParoleButton *button, guint keysym , ParoleButtonKey k
     return TRUE;
 }
 
+/**
+ * parole_button_setup:
+ * @button : the #ParoleButton instance to handle keypresses.
+ *
+ * Setup Parole's keyboard mappings.
+ **/
 static void
 parole_button_setup (ParoleButton *button)
 {
@@ -200,6 +238,12 @@ parole_button_setup (ParoleButton *button)
 			   parole_button_filter_x_events, button);
 }
 
+/**
+ * parole_button_class_init:
+ * @klass: a #ParoleButtonClass instance.
+ *
+ * Initialize a #ParoleButtonClass instance.
+ **/
 static void
 parole_button_class_init(ParoleButtonClass *klass)
 {
@@ -219,6 +263,12 @@ parole_button_class_init(ParoleButtonClass *klass)
     g_type_class_add_private (klass, sizeof (ParoleButtonPrivate));
 }
 
+/**
+ * parole_button_init:
+ * @button : a #ParoleButton instance.
+ *
+ * Initialize a #ParoleButton instance.
+ **/
 static void
 parole_button_init (ParoleButton *button)
 {
@@ -230,12 +280,23 @@ parole_button_init (ParoleButton *button)
     parole_button_setup (button);
 }
 
+/**
+ * parole_button_finalize:
+ * @object : a base #GObject to be made into a #ParoleButton object.
+ *
+ * Finalize a #ParoleButton object.
+ **/
 static void
 parole_button_finalize (GObject *object)
 {
     G_OBJECT_CLASS(parole_button_parent_class)->finalize(object);
 }
 
+/**
+ * parole_button_new:
+ *
+ * Create a new #ParoleButton instance.
+ **/
 ParoleButton *
 parole_button_new (void)
 {