libeek: add field description for GTK-DOC

.gitignore

@@ -28,9 +28,6 @@ missing
 stamp-h1
 libkeyactor*.tar.*
 mkinstalldirs
-docs/reference/eek/eek-overrides.txt
-docs/reference/eek/eek-sections.txt
-docs/reference/eek/eek.types
 m4/*.m4
 gtk-doc.make
 eek/eek-special-keysym-labels.h
@@ -42,6 +39,7 @@ tests/eek-xkb-test
 src/eekboard
 docs/reference/eek/*.stamp
 docs/reference/eek/*.txt
+!/docs/reference/eek/eek-sections.txt
 docs/reference/eek/xml
 docs/reference/eek/html
 docs/reference/eek/eek.signals

README

@@ -20,22 +20,23 @@ lot of bugs and lacks documentation.
 
 * libeek API (not fixed)
 
-libeek provides only two kinds of objects.  One is "keyboard element"
+Since libeek is designed as simple as possible, it provides only two
-and another is "keyboard layout engine".  A keyboard element
+kinds of objects.  One is "keyboard element" and another is "keyboard
-represents either a keyboard, a section, or a key.  Each element
+layout engine".  A keyboard element represents either a keyboard, a
-implements the Builder pattern[1] so that it can be converted into a
+section, or a key.  Each element implements the Builder pattern[1] so
-UI widget (ClutterActor, GTK+ button, ...).  A layout engine arranges
+that it can be converted into a UI widget (ClutterActor,
-keyboard elements using information from external configuration
+GtkDrawingArea, ...).  A layout engine arranges keyboard elements
-mechanisms (XKB, matchbox-keyboard layouts in XML, ...)
+using information from external configuration mechanisms (libxklavier,
+XKB, matchbox-keyboard layouts in XML, ...)
 
-Here is a sample code which utilizes Clutter-based keyboard elements
+Here is a sample code which utilizes Clutter keyboard elements
-and an XKB-based layout engine:
+and libxklavier layout engine:
 
  1: EekKeyboard *keyboard;
  2: EekLayout *layout;
  3:
- 4: /* Create a keyboard layout using XKB configuration. */
+ 4: /* Create a keyboard layout using libxklavier configuration. */
- 5: layout = eek_xkb_layout_new (NULL, "kinesis", "in");
+ 5: layout = eek_xkl_layout_new ();
  6:
  7: /* Create a keyboard implemented as ClutterActor. */
  8: keyboard = eek_clutter_keyboard_new (640, 480);

docs/reference/eek/Makefile.am

@@ -77,9 +77,12 @@ EXTRA_HFILES=
 # Header files to ignore when scanning. Use base file name, no paths
 # e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
 IGNORE_HFILES= eek-private.h \
-	eek-keysym.h \
+	eek-drawing.h \
-	config.h \
+	eek-clutter-key.h \
-	$(NULL)
+	eek-clutter-section.h \
+	eek-clutter-key-actor.h \
+	eek-clutter-drawing-context.h \
+	config.h
 
 # Images to copy into HTML directory.
 # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
@@ -107,8 +110,7 @@ GTKDOC_LIBS = $(top_srcdir)/eek/libeek.la \
 	$(top_srcdir)/eek/libeek-xkl.la \
 	$(GOBJECT2_LIBS) \
 	$(CLUTTER_LIBS) \
-	$(XKB_LIBS) \
+	$(XKB_LIBS)
-	$(NULL)
 
 # This includes the standard gtk-doc make rules, copied by gtkdocize.
 include $(top_srcdir)/gtk-doc.make

docs/reference/eek/eek-docs.sgml

@@ -23,10 +23,12 @@
     <xi:include href="xml/eek-types.xml"/>
   </chapter>
   <chapter>
-    <title>Clutter keyboard elements</title>
+    <title>Clutter keyboard</title>
     <xi:include href="xml/eek-clutter-keyboard.xml"/>
-    <xi:include href="xml/eek-clutter-section.xml"/>
+  </chapter>
-    <xi:include href="xml/eek-clutter-key.xml"/>
+  <chapter>
+    <title>GTK keyboard</title>
+    <xi:include href="xml/eek-gtk-keyboard.xml"/>
   </chapter>
   <chapter>
     <title>XKB layout engine</title>

eek/eek-clutter-key-actor.c

@@ -19,11 +19,6 @@
  * 02110-1301 USA
  */
 
-/**
- * SECTION:eek-clutter-key-actor
- * @short_description: Custom #ClutterActor drawing a key shape
- */
-
 #include <cogl/cogl.h>
 #include <cogl/cogl-pango.h>
 

eek/eek-clutter-key.c

@@ -18,10 +18,6 @@
  * 02110-1301 USA
  */
 
-/**
- * SECTION:eek-clutter-key
- * @short_description: #EekKey embedding a #ClutterActor
- */
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif  /* HAVE_CONFIG_H */

eek/eek-clutter-section.c

@@ -18,10 +18,6 @@
  * 02110-1301 USA
  */
 
-/**
- * SECTION:eek-clutter-section
- * @short_description: #EekSection embedding a #ClutterActor
- */
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif  /* HAVE_CONFIG_H */

eek/eek-container.h

@@ -42,10 +42,16 @@ struct _EekContainer
     /*< private >*/
     EekElement parent;
 
-    /*< public >*/
     EekContainerPrivate *priv;
 };
 
+/**
+ * EekContainerClass:
+ * @foreach_child: virtual function for iterating over the container's children
+ * @find: virtual function for looking up a child
+ * @child_added: class handler for #EekContainer::child-added
+ * @child_removed: class handler for #EekContainer::child-added
+ */
 struct _EekContainerClass
 {
     /*< private >*/
@@ -64,9 +70,6 @@ struct _EekContainerClass
     EekElement *(* find)             (EekContainer  *self,
                                       EekCompareFunc func,
                                       gpointer       user_data);
-    EekElement *(* find_by_position) (EekContainer  *self,
-                                      gdouble        x,
-                                      gdouble        y);
 
     /* signals */
     void        (* child_added)      (EekContainer  *self,

eek/eek-element.c

@@ -317,7 +317,7 @@ eek_element_set_bounds (EekElement  *element,
  *
  * Get the bounding box of @element.  Note that if @element has
  * parent, position of @bounds are relative to the parent.  To obtain
- * the absolute position, use #eek_element_get_absolute_position().
+ * the absolute position, use eek_element_get_absolute_position().
  */
 void
 eek_element_get_bounds (EekElement  *element,

eek/eek-gtk-keyboard.c

@@ -20,7 +20,7 @@
 
 /**
  * SECTION:eek-gtk-keyboard
- * @short_description: #EekKeyboard embedding a #GtkActor
+ * @short_description: #EekKeyboard that can be converted into a #GtkWidget
  */
 #include <string.h>
 

eek/eek-key.h

@@ -44,6 +44,24 @@ struct _EekKey
     EekKeyPrivate *priv;
 };
 
+/**
+ * EekKeyClass:
+ * @set_keycode: virtual function for setting keycode of the key
+ * @get_keycode: virtual function for getting keycode of the key
+ * @set_keysyms: virtual function for setting symbol matrix of the key
+ * @get_keysyms: virtual function for getting symbol matrix of the key
+ * @get_keysym: virtual function for getting the current symbol of the key
+ * @set_index: virtual function for setting position of the key in the
+ * section
+ * @get_index: virtual function for getting position of the key in the
+ * section
+ * @set_outline: virtual function for setting outline shape of the key
+ * @get_outline: virtual function for getting outline shape of the key
+ * @set_keysym_index: virtual function for setting group and level of the key
+ * @get_keysym_index: virtual function for getting group and level of the key
+ * @pressed: class handler for #EekKey::pressed signal
+ * @released: class handler for #EekKey::released signal
+ */
 struct _EekKeyClass
 {
     /*< private >*/

eek/eek-keyboard.h

@@ -45,6 +45,18 @@ struct _EekKeyboard
     EekKeyboardPrivate *priv;
 };
 
+/**
+ * EekKeyboardClass:
+ * @set_keysym_index: virtual function for setting group and level of
+ * the entire keyboard
+ * @get_keysym_index: virtual function for getting group and level of
+ * the entire keyboard
+ * @create_section: virtual function for creating a section
+ * @set_layout: virtual function for setting layout engine
+ * @find_key_by_keycode: virtual function for finding a key in the
+ * keyboard by keycode
+ * @realize: virtual function for applying a layout to the keyboard
+ */
 struct _EekKeyboardClass
 {
     /*< private >*/

eek/eek-keysym.h

@@ -22,9 +22,30 @@
 
 #include <glib-object.h>
 
+/**
+ * EEK_INVALID_KEYSYM:
+ *
+ * Pseudo keysym used for error reporting.
+ */
 #define EEK_INVALID_KEYSYM ((guint)(-1))
+
+/**
+ * EEK_INVALID_KEYCODE:
+ *
+ * Pseudo keycode used for error reporting.
+ */
 #define EEK_INVALID_KEYCODE ((guint)(-1))
 
+/**
+ * EekKeysymCategory:
+ * @EEK_KEYSYM_CATEGORY_LETTER: the symbol represents an alphabet letter
+ * @EEK_KEYSYM_CATEGORY_FUNCTION: the symbol represents a function
+ * @EEK_KEYSYM_CATEGORY_KEYNAME: the symbol does not have meaning but
+ * have a name
+ * @EEK_KEYSYM_CATEGORY_UNKNOWN: used for error reporting
+ *
+ * Category of the key symbols.
+ */
 typedef enum {
     EEK_KEYSYM_CATEGORY_LETTER,
     EEK_KEYSYM_CATEGORY_FUNCTION,

eek/eek-layout.h

@@ -34,6 +34,14 @@ G_BEGIN_DECLS
 typedef struct _EekLayoutIface EekLayoutIface;
 typedef struct _EekLayout EekLayout;
 
+/**
+ * EekLayoutIface:
+ * @apply: virtual function for applying the layout to a keyboard
+ * @get_group: virtual function for getting the current group setting
+ * of the layout
+ * @group_changed: class handler for #EekLayout::group-changed signal
+ * @changed: class handler for #EekLayout::changed signal
+ */
 struct _EekLayoutIface
 {
     /*< private >*/

eek/eek-section.h

@@ -44,6 +44,17 @@ struct _EekSection
     EekSectionPrivate *priv;
 };
 
+/**
+ * EekSectionClass:
+ * @set_angle: virtual function for setting rotation angle of the section
+ * @get_angle: virtual function for getting rotation angle of the section
+ * @get_n_rows: virtual function for getting the number of rows in the section
+ * @add_row: virtual function for adding a new row to the section
+ * @get_row: virtual function for accessing a row in the section
+ * @create_key: virtual function for creating key in the section
+ * @find_key_by_keycode: virtual function for accessing a key in the
+ * section by keycode
+ */
 struct _EekSectionClass
 {
     /*< private >*/