Add doc-comments.

eek/eek-container.c

@@ -143,6 +143,14 @@ eek_container_class_init (EekContainerClass *klass)
     gobject_class->finalize = eek_container_finalize;
     gobject_class->dispose = eek_container_dispose;
 
+    /**
+     * EekContainer::child-added:
+     * @container: an #EekContainer
+     * @element: an #EekElement
+     *
+     * The ::child-added signal is emitted each time an element is
+     * added to @container.
+     */
     signals[CHILD_ADDED] =
         g_signal_new ("child-added",
                       G_TYPE_FROM_CLASS(gobject_class),
@@ -153,6 +161,14 @@ eek_container_class_init (EekContainerClass *klass)
                       G_TYPE_NONE, 1,
                       EEK_TYPE_ELEMENT);
 
+    /**
+     * EekContainer::child-removed:
+     * @container: an #EekContainer
+     * @element: an #EekElement
+     *
+     * The ::child-removed signal is emitted each time an element is
+     * removed from @container.
+     */
     signals[CHILD_REMOVED] =
         g_signal_new ("child-removed",
                       G_TYPE_FROM_CLASS(gobject_class),
@@ -174,6 +190,14 @@ eek_container_init (EekContainer *self)
     priv->children = NULL;
 }
 
+/**
+ * eek_container_foreach_child:
+ * @container: an #EekContainer
+ * @callback: an #EekCallback
+ * @user_data: additional data passed to @callback
+ *
+ * Enumerate children of @container and run @callback with each child.
+ */
 void
 eek_container_foreach_child (EekContainer *container,
                              EekCallback   callback,
@@ -185,6 +209,15 @@ eek_container_foreach_child (EekContainer *container,
                                                        user_data);
 }
 
+/**
+ * eek_container_find:
+ * @container: an #EekContainer
+ * @func: function to be used to compare two children
+ * @user_data: additional data passed to @func
+ *
+ * Find a child which matches the criteria supplied as @func, in @container.
+ * Returns: an #EekElement or NULL on failure
+ */
 EekElement *
 eek_container_find (EekContainer  *container,
                     EekCompareFunc func,

eek/eek-element.c

@@ -203,6 +203,13 @@ eek_element_init (EekElement *self)
     memset (&priv->bounds, 0, sizeof priv->bounds);
 }
 
+/**
+ * eek_element_set_name:
+ * @element: an #EekElement
+ * @name: name of @element
+ *
+ * Set the name of @element to @name.
+ */
 void
 eek_element_set_name (EekElement  *element,
                       const gchar *name)
@@ -211,6 +218,13 @@ eek_element_set_name (EekElement  *element,
     EEK_ELEMENT_GET_CLASS(element)->set_name (element, name);
 }
 
+/**
+ * eek_element_get_name:
+ * @element: an #EekElement
+ *
+ * Get the name of @element.
+ * Returns: the name of @element or NULL when the name is not set
+ */
 G_CONST_RETURN gchar *
 eek_element_get_name (EekElement  *element)
 {
@@ -218,6 +232,13 @@ eek_element_get_name (EekElement  *element)
     return EEK_ELEMENT_GET_CLASS(element)->get_name (element);
 }
 
+/**
+ * eek_element_set_bounds:
+ * @element: an #EekElement
+ * @bounds: bounding box of @element
+ *
+ * Set the bounding box of @element to @bounds.
+ */
 void
 eek_element_set_bounds (EekElement  *element,
                         EekBounds   *bounds)
@@ -226,6 +247,13 @@ eek_element_set_bounds (EekElement  *element,
     EEK_ELEMENT_GET_CLASS(element)->set_bounds (element, bounds);
 }
 
+/**
+ * eek_element_get_bounds:
+ * @element: an #EekElement
+ * @bounds: pointer where bounding box of @element will be stored
+ *
+ * Get the bounding box of @element.
+ */
 void
 eek_element_get_bounds (EekElement  *element,
                         EekBounds   *bounds)

eek/eek-key.c

@@ -456,6 +456,13 @@ eek_key_class_init (EekKeyClass *klass)
                               G_PARAM_READWRITE);
     g_object_class_install_property (gobject_class, PROP_LEVEL, pspec);
 
+    /**
+     * EekKey::pressed:
+     * @key: an #EekKey
+     *
+     * The ::pressed signal is emitted each time @key is shifted to
+     * the pressed state.
+     */
     signals[PRESSED] =
         g_signal_new ("pressed",
                       G_TYPE_FROM_CLASS(gobject_class),
@@ -466,7 +473,14 @@ eek_key_class_init (EekKeyClass *klass)
                       g_cclosure_marshal_VOID__VOID,
                       G_TYPE_NONE, 0);
 
-    signals[RELEASED] =
+    /**
+     * EekKey::released:
+     * @key: an #EekKey
+     *
+     * The ::released signal is emitted each time @key is shifted to
+     * the released state.
+     */
+   signals[RELEASED] =
         g_signal_new ("released",
                       G_TYPE_FROM_CLASS(gobject_class),
                       G_SIGNAL_RUN_FIRST,
@@ -490,6 +504,13 @@ eek_key_init (EekKey *self)
     priv->group = priv->level = 0;
 }
 
+/**
+ * eek_key_set_keycode:
+ * @key: an #EekKey
+ * @keycode: keycode
+ *
+ * Set keycode of @key to @keycode.
+ */
 void
 eek_key_set_keycode (EekKey *key,
                      guint   keycode)
@@ -498,6 +519,13 @@ eek_key_set_keycode (EekKey *key,
     EEK_KEY_GET_CLASS(key)->set_keycode (key, keycode);
 }
 
+/**
+ * eek_key_get_keycode:
+ * @key: an #EekKey
+ *
+ * Get keycode of @key.
+ * Returns: keycode or %EEK_INVALID_KEYCODE on failure
+ */
 guint
 eek_key_get_keycode (EekKey *key)
 {
@@ -505,6 +533,16 @@ eek_key_get_keycode (EekKey *key)
     return EEK_KEY_GET_CLASS(key)->get_keycode (key);
 }
 
+/**
+ * eek_key_set_keysyms:
+ * @key: an #EekKey
+ * @keysyms: symbol matrix of @key
+ * @num_groups: number of groups (rows) of @keysyms
+ * @num_levels: number of levels (columns) of @keysyms
+ *
+ * Set the symbol matrix of @key to @keysyms.  The length of @keysyms
+ * is @num_groups * @num_levels.
+ */
 void
 eek_key_set_keysyms (EekKey *key,
                      guint  *keysyms,
@@ -515,6 +553,18 @@ eek_key_set_keysyms (EekKey *key,
     EEK_KEY_GET_CLASS(key)->set_keysyms (key, keysyms, num_groups, num_levels);
 }
 
+/**
+ * eek_key_get_keysyms:
+ * @key: an #EekKey
+ * @keysyms: pointer where symbol matrix of @key will be stored
+ * @num_groups: pointer where the number of groups (rows) of @keysyms
+ * will be stored
+ * @num_levels: pointer where the number of levels (columns) of
+ * @keysyms will be stored
+ *
+ * Get the symbol matrix of @key.  If either @keysyms, @num_groups, or
+ * @num_levels are NULL, this function does not try to get the value.
+ */
 void
 eek_key_get_keysyms (EekKey *key,
                      guint **keysyms,
@@ -525,6 +575,13 @@ eek_key_get_keysyms (EekKey *key,
     EEK_KEY_GET_CLASS(key)->get_keysyms (key, keysyms, num_groups, num_levels);
 }
 
+/**
+ * eek_key_get_keysym:
+ * @key: an #EekKey
+ *
+ * Get the current symbol of @key.
+ * Returns: a symbol or %EEK_INVALID_KEYSYM on failure
+ */
 guint
 eek_key_get_keysym (EekKey *key)
 {
@@ -532,6 +589,15 @@ eek_key_get_keysym (EekKey *key)
     return EEK_KEY_GET_CLASS(key)->get_keysym (key);
 }
 
+/**
+ * eek_key_set_index:
+ * @key: an #EekKey
+ * @column: column index of @key in #EekSection
+ * @row: row index of @key in #EekSection
+ *
+ * Set the index of @key (i.e. logical location of @key in
+ * #EekSection) to @column and @row.
+ */
 void
 eek_key_set_index (EekKey *key,
                    gint    column,
@@ -541,6 +607,15 @@ eek_key_set_index (EekKey *key,
     EEK_KEY_GET_CLASS(key)->set_index (key, column, row);
 }
 
+/**
+ * eek_key_get_index:
+ * @key: an #EekKey
+ * @column: pointer where the column index of @key in #EekSection will be stored
+ * @row: pointer where the row index of @key in #EekSection will be stored
+ *
+ * Get the index of @key (i.e. logical location of @key in
+ * #EekSection).
+ */
 void
 eek_key_get_index (EekKey *key,
                    gint   *column,
@@ -550,6 +625,13 @@ eek_key_get_index (EekKey *key,
     EEK_KEY_GET_CLASS(key)->get_index (key, column, row);
 }
 
+/**
+ * eek_key_set_outline:
+ * @key: an #EekKey
+ * @outline: outline of @key
+ *
+ * Set the outline shape of @key to @outline.
+ */
 void
 eek_key_set_outline (EekKey     *key,
                      EekOutline *outline)
@@ -558,6 +640,13 @@ eek_key_set_outline (EekKey     *key,
     EEK_KEY_GET_CLASS(key)->set_outline (key, outline);
 }
 
+/**
+ * eek_key_get_outline:
+ * @key: an #EekKey
+ *
+ * Get the outline shape of @key.
+ * Returns: an #EekOutline pointer or NULL on failure
+ */
 EekOutline *
 eek_key_get_outline (EekKey *key)
 {
@@ -565,6 +654,15 @@ eek_key_get_outline (EekKey *key)
     return EEK_KEY_GET_CLASS(key)->get_outline (key);
 }
 
+/**
+ * eek_key_set_keysym_index:
+ * @key: an #EekKey
+ * @group: group (row) index of @key
+ * @level: level (column) index of @key
+ *
+ * Set the current group and/or level index of @key in its symbol
+ * matrix to @group and @level.
+ */
 void
 eek_key_set_keysym_index (EekKey *key,
                           gint    group,
@@ -574,6 +672,15 @@ eek_key_set_keysym_index (EekKey *key,
     EEK_KEY_GET_CLASS(key)->set_keysym_index (key, group, level);
 }
 
+/**
+ * eek_key_get_keysym_index:
+ * @key: an #EekKey
+ * @group: pointer where group (row) index of @key will be stored
+ * @level: pointer where level (column) index of @key will be stored
+ *
+ * Get the current group and/or level index of @key in its symbol
+ * matrix.
+ */
 void
 eek_key_get_keysym_index (EekKey *key,
                           gint   *group,

eek/eek-keyboard.c

@@ -339,6 +339,14 @@ eek_keyboard_class_init (EekKeyboardClass *klass)
                                      PROP_LEVEL,
                                      pspec);
 
+    /**
+     * EekKeyboard::key-pressed:
+     * @keyboard: an #EekKeyboard
+     * @key: an #EekKey
+     *
+     * The ::key-pressed signal is emitted each time a key in @keyboard
+     * is shifted to the pressed state.
+     */
     signals[KEY_PRESSED] =
         g_signal_new ("key-pressed",
                       G_TYPE_FROM_CLASS(gobject_class),
@@ -351,6 +359,14 @@ eek_keyboard_class_init (EekKeyboardClass *klass)
                       1,
                       EEK_TYPE_KEY);
 
+    /**
+     * EekKeyboard::key-released:
+     * @keyboard: an #EekKeyboard
+     * @key: an #EekKey
+     *
+     * The ::key-released signal is emitted each time a key in @keyboard
+     * is shifted to the released state.
+     */
     signals[KEY_RELEASED] =
         g_signal_new ("key-released",
                       G_TYPE_FROM_CLASS(gobject_class),

eek/eek-layout.c

@@ -47,6 +47,14 @@ eek_layout_base_init (gpointer gobject_class)
     static gboolean is_initialized = FALSE;
 
     if (!is_initialized) {
+        /**
+         * EekLayout::group-changed:
+         * @layout: an #EekLayout that received the signal
+         * @group: group index
+         *
+         * The ::group-changed signal is emitted each time group
+         * configuration of @layout changed.
+         */
         signals[GROUP_CHANGED] =
             g_signal_new ("group-changed",
                           G_TYPE_FROM_INTERFACE(gobject_class),
@@ -57,6 +65,14 @@ eek_layout_base_init (gpointer gobject_class)
                           g_cclosure_marshal_VOID__INT,
                           G_TYPE_NONE, 1,
                           G_TYPE_INT);
+
+        /**
+         * EekLayout::changed:
+         * @layout: an #EekLayout that received the signal
+         *
+         * The ::changed signal is emitted each time @layout changed
+         * and re-layout of #EekKeyboard is needed.
+         */
         signals[CHANGED] =
             g_signal_new ("changed",
                           G_TYPE_FROM_INTERFACE(gobject_class),
@@ -87,6 +103,14 @@ eek_layout_get_type (void)
     return iface_type;
 }
 
+/**
+ * eek_layout_apply:
+ * @layout: an #EekLayout
+ * @keyboard: an #EekKeyboard
+ *
+ * Apply @layout to @keyboard.  This function is rarely called by user
+ * programs but called by the subclasses of #EekKeyboard.
+ */
 void
 eek_layout_apply (EekLayout   *layout,
                   EekKeyboard *keyboard)
@@ -95,6 +119,14 @@ eek_layout_apply (EekLayout   *layout,
     EEK_LAYOUT_GET_IFACE(layout)->apply (layout, keyboard);
 }
 
+/**
+ * eek_layout_get_group:
+ * @layout: an #EekLayout
+ *
+ * Get the group index from the @layout.  This function normally
+ * called after #EekLayout::group-changed signal to change group index
+ * of all the keys in #EekKeyboard at a time.
+ */
 gint
 eek_layout_get_group (EekLayout *layout)
 {

eek/eek-section.c

@@ -269,6 +269,14 @@ eek_section_class_init (EekSectionClass *klass)
                                      PROP_ANGLE,
                                      pspec);
 
+    /**
+     * EekSection::key-pressed:
+     * @section: an #EekSection
+     * @key: an #EekKey
+     *
+     * The ::key-pressed signal is emitted each time a key in @section
+     * is shifted to the pressed state.
+     */
     signals[KEY_PRESSED] =
         g_signal_new ("key-pressed",
                       G_TYPE_FROM_CLASS(gobject_class),
@@ -281,6 +289,14 @@ eek_section_class_init (EekSectionClass *klass)
                       1,
                       EEK_TYPE_KEY);
 
+    /**
+     * EekSection::key-released:
+     * @section: an #EekSection
+     * @key: an #EekKey
+     *
+     * The ::key-released signal is emitted each time a key in @section
+     * is shifted to the released state.
+     */
     signals[KEY_RELEASED] =
         g_signal_new ("key-released",
                       G_TYPE_FROM_CLASS(gobject_class),