Add introspection and vala support. Fixes: https://bugs.launchpad.net/bugs/582985.

Approved by Mathieu Trudel-Lapierre.

13 files changed, 366 insertions, 40 deletions

diff --git a/configure.ac b/configure.ac
index 31d1340..1cb4bd4 100644
--- a/configure.ac
+++ b/configure.ac
@@ -123,6 +123,14 @@ AC_SUBST(COVERAGE_CFLAGS)
 AC_SUBST(COVERAGE_CXXFLAGS)
 AC_SUBST(COVERAGE_LDFLAGS)
 
+dnl = GObject Introspection ===================================================
+
+GOBJECT_INTROSPECTION_CHECK([0.6.7])
+
+dnl = Vala API Generation =====================================================
+
+AC_PATH_PROG([VALA_API_GEN], [vapigen])
+
 dnl = Google Test Framework ===================================================
 
 m4_include([m4/gtest.m4])
@@ -152,6 +160,7 @@ echo " ==============================="
 echo ""
 echo " Prefix       : ${prefix}"
 echo " gcov         : ${use_gcov}"
+echo " introspection: ${enable_introspection}"
 echo ""
 echo " Documentation: ${enable_gtk_doc}"
 echo ""
diff --git a/debian/control b/debian/control
index e1689d5..7c9d627 100644
--- a/debian/control
+++ b/debian/control
@@ -10,6 +10,11 @@ Build-Depends: debhelper (>= 9),
                libglib2.0-dev (>=2.14.0),
                libgtk-3-dev (>= 3.0),
                gtk-doc-tools,
+               gobject-introspection,
+               libgirepository1.0-dev,
+               gir1.2-glib-2.0,
+               gir1.2-gtk-2.0,
+               valac-0.16
 Standards-Version: 3.9.3
 Homepage: https://launchpad.net/ido
 # If you aren't a member of ~indicator-applet-developers but need to upload
@@ -43,3 +48,15 @@ Description: Shared library providing extra gtk menu items for display in
  system indicators
  .
  This package contains files that are needed to build GTK+ 3 applications.
+
+Package: gir1.2-ido3-0.1
+Section: libs
+Architecture: any
+Depends: ${misc:Depends},
+         libido3-0.1-0 (>= ${binary:Version}),
+         ${gir:Depends}
+Description: Typelib file for libido3-0.1
+ Shared library providing extra gtk menu items for display in system indicators.
+ .
+ This package can be used by other packages using the GIRepository format to
+ generate dynamic bindings for libido3-0.1.
diff --git a/debian/gir1.2-ido3-0.1.install b/debian/gir1.2-ido3-0.1.install
new file mode 100644
index 0000000..cbe4832
--- /dev/null
+++ b/debian/gir1.2-ido3-0.1.install
@@ -0,0 +1 @@
+usr/lib/*/girepository-1.0 /usr/lib
diff --git a/debian/libido3-0.1-dev.install b/debian/libido3-0.1-dev.install
index 6ac8136..a3208de 100644
--- a/debian/libido3-0.1-dev.install
+++ b/debian/libido3-0.1-dev.install
@@ -1,3 +1,5 @@
 usr/include/libido3-*
 usr/lib/*/pkgconfig/libido3-*
 usr/lib/*/libido3-*.so
+usr/share/vala
+usr/share/gir-1.0
diff --git a/src/Makefile.am b/src/Makefile.am
index 017874f..e14efbf 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -1,3 +1,5 @@
+CLEANFILES =
+
 VER=3
 lib_LTLIBRARIES = libido3-0.1.la
 
@@ -94,3 +96,54 @@ DISTCLEANFILES =			\
 	idotypebuiltins.h		\
 	idotypebuiltins.c
 
+-include $(INTROSPECTION_MAKEFILE)
+INTROSPECTION_GIRS =
+INTROSPECTION_SCANNER_ARGS = \
+        --symbol-prefix=ido \
+        --warn-all \
+        --identifier-prefix=Ido
+
+if HAVE_INTROSPECTION
+
+Ido3-0.1.gir: libido3-0.1.la
+Ido3_0_1_gir_INCLUDES = Gtk-3.0
+Ido3_0_1_gir_CFLAGS =
+Ido3_0_1_gir_LIBS = libido3-0.1.la
+Ido3_0_1_gir_FILES = \
+	idocalendarmenuitem.h		\
+	idoentrymenuitem.h		\
+	idomessagedialog.h		\
+	idorange.h			\
+	idoscalemenuitem.h		\
+	idoswitchmenuitem.h		\
+	idotimeline.h			\
+	$(libido_0_1_la_SOURCES)
+Ido3_0_1_gir_NAMESPACE = Ido3
+Ido3_0_1_gir_VERSION = 0.1
+Ido3_0_1_gir_SCANNER_FLAGS = $(INTROSPECTION_SCANNER_ARGS)
+
+INTROSPECTION_GIRS += Ido3-0.1.gir
+
+girdir = $(datadir)/gir-1.0
+gir_DATA = $(INTROSPECTION_GIRS)
+
+typelibdir = $(libdir)/girepository-1.0
+typelib_DATA = $(INTROSPECTION_GIRS:.gir=.typelib)
+
+CLEANFILES += $(gir_DATA) $(typelib_DATA)
+
+endif
+
+if HAVE_INTROSPECTION
+
+vapidir = $(datadir)/vala/vapi
+vapi_DATA = Ido3-0.1.vapi
+
+Ido3-0.1.vapi: Ido3-0.1.gir
+	$(VALA_API_GEN) --library=Ido3-0.1 \
+			--pkg gtk+-3.0 \
+			$<
+
+CLEANFILES += $(vapi_DATA)
+
+endif
diff --git a/src/idocalendarmenuitem.c b/src/idocalendarmenuitem.c
index baae342..a818c13 100644
--- a/src/idocalendarmenuitem.c
+++ b/src/idocalendarmenuitem.c
@@ -324,21 +324,44 @@ calendar_day_selected_double_click_cb (GtkWidget        *widget,
   g_signal_emit_by_name (item, "day-selected-double-click", NULL);
 }
 
-/* Public API */
+/**
+ * ido_calendar_menu_item_new:
+ *
+ * Creates a new #IdoCalendarMenuItem
+ *
+ * Return Value: a new #IdoCalendarMenuItem.
+ **/
 GtkWidget *
 ido_calendar_menu_item_new (void)
 {
   return g_object_new (IDO_TYPE_CALENDAR_MENU_ITEM, NULL);
 }
 
+/**
+ * ido_calendar_menu_item_get_calendar:
+ * @menuitem: A #IdoCalendarMenuItem
+ *
+ * Returns the calendar associated with this menu item.
+ *
+ * Return Value: (transfer none): The #GtkCalendar used in this item.
+ */
 GtkWidget *
-ido_calendar_menu_item_get_calendar (IdoCalendarMenuItem *item)
+ido_calendar_menu_item_get_calendar (IdoCalendarMenuItem *menuitem)
 {
-  g_return_val_if_fail (IDO_IS_CALENDAR_MENU_ITEM (item), NULL);
+  g_return_val_if_fail (IDO_IS_CALENDAR_MENU_ITEM (menuitem), NULL);
 
-  return item->priv->calendar;
+  return menuitem->priv->calendar;
 }
 
+/**
+ * ido_calendar_menu_item_mark_day:
+ * @menuitem: A #IdoCalendarMenuItem
+ * @day: the day number to unmark between 1 and 31.
+ *
+ * Places a visual marker on a particular day. 
+ *
+ * Return Value: #TRUE
+ */
 gboolean
 ido_calendar_menu_item_mark_day	(IdoCalendarMenuItem *menuitem, guint day)
 {
@@ -348,6 +371,15 @@ ido_calendar_menu_item_mark_day	(IdoCalendarMenuItem *menuitem, guint day)
   return TRUE;
 }
 
+/**
+ * ido_calendar_menu_item_unmark_day:
+ * @menuitem: A #IdoCalendarMenuItem
+ * @day: the day number to unmark between 1 and 31.
+ * 
+ * Removes the visual marker from a particular day.
+ *
+ * Return Value: #TRUE
+ */
 gboolean
 ido_calendar_menu_item_unmark_day (IdoCalendarMenuItem *menuitem, guint day)
 {
@@ -357,6 +389,12 @@ ido_calendar_menu_item_unmark_day (IdoCalendarMenuItem *menuitem, guint day)
   return TRUE;
 }
 
+/**
+ * ido_calendar_menu_item_clear_marks:
+ * @menuitem: A #IdoCalendarMenuItem
+ *
+ * Remove all visual markers. 
+ */
 void
 ido_calendar_menu_item_clear_marks (IdoCalendarMenuItem *menuitem)
 {
@@ -365,6 +403,13 @@ ido_calendar_menu_item_clear_marks (IdoCalendarMenuItem *menuitem)
   gtk_calendar_clear_marks(GTK_CALENDAR (menuitem->priv->calendar));
 }
 
+/**
+ * ido_calendar_menu_item_set_display_options:
+ * @menuitem: A #IdoCalendarMenuItem
+ * @flags: the display options to set
+ *
+ * Set the display options for the calendar.
+ */
 void
 ido_calendar_menu_item_set_display_options (IdoCalendarMenuItem *menuitem, GtkCalendarDisplayOptions flags)
 {
@@ -373,6 +418,14 @@ ido_calendar_menu_item_set_display_options (IdoCalendarMenuItem *menuitem, GtkCa
   gtk_calendar_set_display_options (GTK_CALENDAR (menuitem->priv->calendar), flags);
 }
 
+/**
+ * ido_calendar_menu_item_get_display_options:
+ * @menuitem: A #IdoCalendarMenuItem
+ *
+ * Get the display options for the calendar.
+ *
+ * Return Value: the display options in use
+ */
 GtkCalendarDisplayOptions
 ido_calendar_menu_item_get_display_options (IdoCalendarMenuItem *menuitem)
 {
@@ -381,6 +434,15 @@ ido_calendar_menu_item_get_display_options (IdoCalendarMenuItem *menuitem)
   return gtk_calendar_get_display_options (GTK_CALENDAR (menuitem->priv->calendar));
 }
 
+/**
+ * ido_calendar_menu_item_get_date:
+ * @menuitem: A #IdoCalendarMenuItem
+ * @year: (out) (allow-none): location to store the year as a decimal number (e.g. 2011), or #NULL.
+ * @month: (out) (allow-none): location to store the month number (between 0 and 11), or #NULL.
+ * @day: (out) (allow-none): location to store the day number (between 1 and 31), or #NULL.
+ *
+ * Gets the selected date.
+ */
 void 
 ido_calendar_menu_item_get_date (IdoCalendarMenuItem *menuitem,
                                  guint *year,
@@ -391,6 +453,17 @@ ido_calendar_menu_item_get_date (IdoCalendarMenuItem *menuitem,
   gtk_calendar_get_date (GTK_CALENDAR (menuitem->priv->calendar), year, month, day);
 }
 
+/**
+ * ido_calendar_menu_item_set_date:
+ * @menuitem: A #IdoCalendarMenuItem
+ * @year: the year to show (e.g. 2011).
+ * @month: a month number (between 0 and 11).
+ * @day: The day number (between 1 and 31).
+ *
+ * Set the date shown on the calendar.
+ *
+ * Return Value: #TRUE
+ */
 gboolean
 ido_calendar_menu_item_set_date (IdoCalendarMenuItem *menuitem,
                                  guint year,
@@ -402,6 +475,3 @@ ido_calendar_menu_item_set_date (IdoCalendarMenuItem *menuitem,
   gtk_calendar_select_day (GTK_CALENDAR (menuitem->priv->calendar), day);
   return TRUE;
 }
-
-
-
diff --git a/src/idoentrymenuitem.c b/src/idoentrymenuitem.c
index 5390d0b..5b5a3fb 100644
--- a/src/idoentrymenuitem.c
+++ b/src/idoentrymenuitem.c
@@ -260,17 +260,31 @@ entry_move_focus_cb (GtkWidget        *widget,
                          GTK_DIR_TAB_FORWARD);
 }
 
-/* Public API */
+/**
+ * ido_entry_menu_item_new:
+ *
+ * Creates a new #IdoEntryMenuItem.
+ *
+ * Return Value: the newly created #IdoEntryMenuItem.
+ */
 GtkWidget *
 ido_entry_menu_item_new (void)
 {
   return g_object_new (IDO_TYPE_ENTRY_MENU_ITEM, NULL);
 }
 
+/**
+ * ido_entry_menu_item_get_entry:
+ * @menuitem: The #IdoEntryMenuItem.
+ *
+ * Get the #GtkEntry used in this menu item.
+ *
+ * Return Value: (transfer none): The #GtkEntry inside this menu item.
+ */
 GtkWidget *
-ido_entry_menu_item_get_entry (IdoEntryMenuItem *item)
+ido_entry_menu_item_get_entry (IdoEntryMenuItem *menuitem)
 {
-  g_return_val_if_fail (IDO_IS_ENTRY_MENU_ITEM (item), NULL);
+  g_return_val_if_fail (IDO_IS_ENTRY_MENU_ITEM (menuitem), NULL);
 
-  return item->priv->entry;
+  return menuitem->priv->entry;
 }
diff --git a/src/idomessagedialog.c b/src/idomessagedialog.c
index 41ff2e7..f2c2e93 100644
--- a/src/idomessagedialog.c
+++ b/src/idomessagedialog.c
@@ -258,7 +258,7 @@ ido_message_dialog_init (IdoMessageDialog *dialog)
  * dialog it will expand to provide the secondary message
  * and the action buttons.
  *
- * Return value: a new #IdoMessageDialog
+ * Return Value: a new #IdoMessageDialog
  **/
 GtkWidget*
 ido_message_dialog_new (GtkWindow      *parent,
@@ -305,6 +305,25 @@ ido_message_dialog_new (GtkWindow      *parent,
   return widget;
 }
 
+/**
+ * ido_message_dialog_new_with_markup:
+ * @parent: transient parent, or %NULL for none
+ * @flags: flags
+ * @type: type of message
+ * @buttons: a set of buttons to use
+ * @message_format: printf()-style format string, or %NULL
+ * @Varargs: arguments for @message_format. They will be escaped to allow valid XML.
+ *
+ * Creates a new message dialog, which is based upon
+ * GtkMessageDialog so it shares API and functionality
+ * with it.  IdoMessageDialog differs in that it has two
+ * states.  The initial state hides the action buttons
+ * and the secondary message.  When a user clicks on the
+ * dialog it will expand to provide the secondary message
+ * and the action buttons.
+ *
+ * Return Value: a new #IdoMessageDialog
+ **/
 GtkWidget*
 ido_message_dialog_new_with_markup (GtkWindow      *parent,
                                     GtkDialogFlags  flags,
diff --git a/src/idorange.c b/src/idorange.c
index 3e88fd9..acdfa5d 100644
--- a/src/idorange.c
+++ b/src/idorange.c
@@ -172,6 +172,8 @@ ido_range_init (IdoRange *range)
  * @style: The range style
  *
  * Creates a new #IdoRange widget.
+ *
+ * Return Value: A new #IdoRange
  **/
 GtkWidget *
 ido_range_new (GObject *adj,
diff --git a/src/idoscalemenuitem.c b/src/idoscalemenuitem.c
index 986d9a7..25460bb 100644
--- a/src/idoscalemenuitem.c
+++ b/src/idoscalemenuitem.c
@@ -309,6 +309,12 @@ ido_scale_menu_item_class_init (IdoScaleMenuItemClass *item_class)
                                                          FALSE,
                                                          G_PARAM_READWRITE));
 
+  /**
+   * IdoScaleMenuItem::slider-grabbed:
+   * @menuitem: The #IdoScaleMenuItem emitting the signal.
+   *
+   * The ::slider-grabbed signal is emitted when the pointer selects the slider. 
+   */
   signals[SLIDER_GRABBED] = g_signal_new ("slider-grabbed",
                                           G_OBJECT_CLASS_TYPE (gobject_class),
                                           G_SIGNAL_RUN_FIRST,
@@ -317,6 +323,12 @@ ido_scale_menu_item_class_init (IdoScaleMenuItemClass *item_class)
                                           g_cclosure_marshal_VOID__VOID,
                                           G_TYPE_NONE, 0);
 
+  /**
+   * IdoScaleMenuItem::slider-released:
+   * @menuitem: The #IdoScaleMenuItem emitting the signal.
+   *
+   * The ::slider-released signal is emitted when the pointer releases the slider.
+   */
   signals[SLIDER_RELEASED] = g_signal_new ("slider-released",
                                            G_OBJECT_CLASS_TYPE (gobject_class),
                                            G_SIGNAL_RUN_FIRST,
@@ -325,6 +337,12 @@ ido_scale_menu_item_class_init (IdoScaleMenuItemClass *item_class)
                                            g_cclosure_marshal_VOID__VOID,
                                            G_TYPE_NONE, 0);
 
+  /**
+   * IdoScaleMenuItem::primary-clicked:
+   * @menuitem: The #IdoScaleMenuItem emitting the signal.
+   *
+   * The ::primary-clicked signal is emitted when the pointer clicks the primary label.
+   */
   signals[PRIMARY_CLICKED] = g_signal_new ("primary-clicked",
                                            G_TYPE_FROM_CLASS (item_class),
                                            G_SIGNAL_RUN_FIRST | G_SIGNAL_NO_RECURSE | G_SIGNAL_NO_HOOKS,
@@ -334,6 +352,12 @@ ido_scale_menu_item_class_init (IdoScaleMenuItemClass *item_class)
                                            G_TYPE_NONE, /* return type */
                                            0 /* n_params */);
 
+  /**
+   * IdoScaleMenuItem::secondary-clicked:
+   * @menuitem: The #IdoScaleMenuItem emitting the signal.
+   *
+   * The ::secondary-clicked signal is emitted when the pointer clicks the secondary label.
+   */
   signals[SECONDARY_CLICKED] = g_signal_new ("secondary-clicked",
                                              G_TYPE_FROM_CLASS (item_class),
                                              G_SIGNAL_RUN_FIRST | G_SIGNAL_NO_RECURSE | G_SIGNAL_NO_HOOKS,
@@ -625,9 +649,10 @@ ido_scale_menu_item_secondary_image_notify (GtkImage         *image,
  * @label: the text of the new menu item.
  * @size: The size style of the range.
  * @adjustment: A #GtkAdjustment describing the slider value.
- * @returns: a new #IdoScaleMenuItem.
  *
  * Creates a new #IdoScaleMenuItem with an empty label.
+ *
+ * Return Value: a new #IdoScaleMenuItem.
  **/
 GtkWidget*
 ido_scale_menu_item_new (const gchar   *label,
@@ -647,9 +672,10 @@ ido_scale_menu_item_new (const gchar   *label,
  * @min: The minimum value of the slider.
  * @max: The maximum value of the slider.
  * @step: The step increment of the slider.
- * @returns: a new #IdoScaleMenuItem.
  *
  * Creates a new #IdoScaleMenuItem containing a label.
+ *
+ * Return Value: a new #IdoScaleMenuItem.
  **/
 GtkWidget*
 ido_scale_menu_item_new_with_range (const gchar  *label,
@@ -671,9 +697,10 @@ ido_scale_menu_item_new_with_range (const gchar  *label,
 /**
  * ido_scale_menu_item_get_scale:
  * @menuitem: The #IdoScaleMenuItem
- * @returns: A pointer to the scale widget.
  *
  * Retrieves the scale widget.
+ *
+ * Return Value: (transfer none): The #IdoRange in this item
  **/
 GtkWidget*
 ido_scale_menu_item_get_scale (IdoScaleMenuItem *menuitem)
@@ -690,10 +717,11 @@ ido_scale_menu_item_get_scale (IdoScaleMenuItem *menuitem)
 /**
  * ido_scale_menu_item_get_style:
  * @menuitem: The #IdoScaleMenuItem
- * @returns: A #IdoScaleMenuItemStyle enum describing the style.
  *
  * Retrieves the type of widgets being used for the primary and
  * secondary widget slots.  This could be images, labels, or nothing.
+ *
+ * Return Value: A #IdoScaleMenuItemStyle enum describing the style.
  **/
 IdoScaleMenuItemStyle
 ido_scale_menu_item_get_style (IdoScaleMenuItem *menuitem)
@@ -707,6 +735,14 @@ ido_scale_menu_item_get_style (IdoScaleMenuItem *menuitem)
   return priv->style;
 }
 
+/**
+ * ido_scale_menu_item_set_style:
+ * @menuitem: The #IdoScaleMenuItem
+ * @style: Set the style use for the primary and secondary widget slots.
+ *
+ * Sets the type of widgets being used for the primary and
+ * secondary widget slots.  This could be images, labels, or nothing.
+ **/
 void
 ido_scale_menu_item_set_style (IdoScaleMenuItem      *menuitem,
                                IdoScaleMenuItemStyle  style)
@@ -725,11 +761,12 @@ ido_scale_menu_item_set_style (IdoScaleMenuItem      *menuitem,
 /**
  * ido_scale_menu_item_get_primary_image:
  * @menuitem: The #IdoScaleMenuItem
- * @returns: A #GtkWidget pointer for the primary image.
  *
  * Retrieves a pointer to the image widget used in the primary slot.
  * Whether this is visible depends upon the return value from
  * ido_scale_menu_item_get_style().
+ *
+ * Return Value: (transfer none): A #GtkWidget pointer for the primary image.
  **/
 GtkWidget *
 ido_scale_menu_item_get_primary_image (IdoScaleMenuItem *menuitem)
@@ -746,11 +783,12 @@ ido_scale_menu_item_get_primary_image (IdoScaleMenuItem *menuitem)
 /**
  * ido_scale_menu_item_get_secondary_image:
  * @menuitem: The #IdoScaleMenuItem
- * @returns: A #GtkWidget pointer for the secondary image.
  *
  * Retrieves a pointer to the image widget used in the secondary slot.
  * Whether this is visible depends upon the return value from
  * ido_scale_menu_item_get_style().
+ *
+ * Return Value: (transfer none): A #GtkWidget pointer for the secondary image.
  **/
 GtkWidget *
 ido_scale_menu_item_get_secondary_image (IdoScaleMenuItem *menuitem)
@@ -767,11 +805,12 @@ ido_scale_menu_item_get_secondary_image (IdoScaleMenuItem *menuitem)
 /**
  * ido_scale_menu_item_get_primary_label:
  * @menuitem: The #IdoScaleMenuItem
- * @returns: A const gchar* string of the label text.
  *
  * Retrieves a string of the text for the primary label widget.
  * Whether this is visible depends upon the return value from
  * ido_scale_menu_item_get_style().
+ *
+ * Return Value: The label text.
  **/
 const gchar*
 ido_scale_menu_item_get_primary_label (IdoScaleMenuItem *menuitem)
@@ -786,13 +825,14 @@ ido_scale_menu_item_get_primary_label (IdoScaleMenuItem *menuitem)
 }
 
 /**
- * ido_scale_menu_item_get_primary_label:
+ * ido_scale_menu_item_get_secondary_label:
  * @menuitem: The #IdoScaleMenuItem
- * @returns: A const gchar* string of the label text.
  *
- * Retrieves a string of the text for the primary label widget.
+ * Retrieves a string of the text for the secondary label widget.
  * Whether this is visible depends upon the return value from
  * ido_scale_menu_item_get_style().
+ *
+ * Return Value: The label text.
  **/
 const gchar*
 ido_scale_menu_item_get_secondary_label (IdoScaleMenuItem *menuitem)
@@ -809,7 +849,7 @@ ido_scale_menu_item_get_secondary_label (IdoScaleMenuItem *menuitem)
 /**
  * ido_scale_menu_item_set_primary_label:
  * @menuitem: The #IdoScaleMenuItem
- * @label: A string containing the label text
+ * @label: The label text
  *
  * Sets the text for the label widget in the primary slot.  This
  * widget will only be visibile if the return value of
@@ -832,11 +872,11 @@ ido_scale_menu_item_set_primary_label (IdoScaleMenuItem *menuitem,
 }
 
 /**
- * ido_scale_menu_item_set_primary_label:
+ * ido_scale_menu_item_set_secondary_label:
  * @menuitem: The #IdoScaleMenuItem
- * @label: A string containing the label text
+ * @label: The label text
  *
- * Sets the text for the label widget in the primary slot.  This
+ * Sets the text for the label widget in the secondary slot.  This
  * widget will only be visibile if the return value of
  * ido_scale_menu_item_get_style() is set to %IDO_SCALE_MENU_ITEM_STYLE_LABEL.
  **/
@@ -859,16 +899,16 @@ ido_scale_menu_item_set_secondary_label (IdoScaleMenuItem *menuitem,
 /**
  * ido_scale_menu_item_primary_clicked:
  * @menuitem: the #IdoScaleMenuItem
- * 
+ *
  * Emits the "primary-clicked" signal.
  *
  * The default handler for this signal lowers the scale's
  * adjustment to its lower bound.
  */
 void
-ido_scale_menu_item_primary_clicked (IdoScaleMenuItem * item)
+ido_scale_menu_item_primary_clicked (IdoScaleMenuItem * menuitem)
 {
-  g_signal_emit (item, signals[PRIMARY_CLICKED], 0);
+  g_signal_emit (menuitem, signals[PRIMARY_CLICKED], 0);
 }
 static void
 default_primary_clicked_handler (IdoScaleMenuItem * item)
@@ -880,18 +920,18 @@ default_primary_clicked_handler (IdoScaleMenuItem * item)
 }
 
 /**
- * ido_scale_menu_item_primary_clicked:
+ * ido_scale_menu_item_secondary_clicked:
  * @menuitem: the #IdoScaleMenuItem
- * 
- * Emits the "primary-clicked" signal.
+ *
+ * Emits the "secondary-clicked" signal.
  *
  * The default handler for this signal raises the scale's
  * adjustment to its upper bound.
  */
 void
-ido_scale_menu_item_secondary_clicked (IdoScaleMenuItem * item)
+ido_scale_menu_item_secondary_clicked (IdoScaleMenuItem * menuitem)
 {
-  g_signal_emit (item, signals[SECONDARY_CLICKED], 0);
+  g_signal_emit (menuitem, signals[SECONDARY_CLICKED], 0);
 }
 static void
 default_secondary_clicked_handler (IdoScaleMenuItem * item)
diff --git a/src/idoscalemenuitem.h b/src/idoscalemenuitem.h
index 81a3474..2d63f3c 100644
--- a/src/idoscalemenuitem.h
+++ b/src/idoscalemenuitem.h
@@ -61,8 +61,8 @@ struct _IdoScaleMenuItemClass
   GtkMenuItemClass parent_class;
 
   /* signal default handlers */
-  void (*primary_clicked)(IdoScaleMenuItem * self);
-  void (*secondary_clicked)(IdoScaleMenuItem * self);
+  void (*primary_clicked)(IdoScaleMenuItem * menuitem);
+  void (*secondary_clicked)(IdoScaleMenuItem * menuitem);
 };
 
 
diff --git a/src/idoswitchmenuitem.c b/src/idoswitchmenuitem.c
index 3831336..10ff1f3 100644
--- a/src/idoswitchmenuitem.c
+++ b/src/idoswitchmenuitem.c
@@ -101,16 +101,27 @@ ido_switch_menu_button_release_event (GtkWidget * widget, GdkEventButton * event
   return TRUE; /* stop the event so that it doesn't trigger popdown() */
 }
 
-/***
-**** Public API
-***/
-
+/**
+ * ido_switch_menu_item_new:
+ *
+ * Creates a new #IdoSwitchMenuItem
+ *
+ * Return Value: a new #IdoSwitchMenuItem.
+ **/
 GtkWidget *
 ido_switch_menu_item_new (void)
 {
   return g_object_new (IDO_TYPE_SWITCH_MENU_ITEM, NULL);
 }
 
+/**
+ * ido_switch_menu_item_get_content_area:
+ * @item: The #IdoSwitchMenuItem.
+ *
+ * Get the #GtkContainer to add additional widgets into.
+ *
+ * Return Value: (transfer none): The #GtkContainer to add additional widgets into.
+ **/
 GtkContainer *
 ido_switch_menu_item_get_content_area (IdoSwitchMenuItem * item)
 {
diff --git a/src/idotimeline.c b/src/idotimeline.c
index c6275ae..24a6935 100644
--- a/src/idotimeline.c
+++ b/src/idotimeline.c
@@ -132,6 +132,12 @@ ido_timeline_class_init (IdoTimelineClass *klass)
 							GDK_TYPE_SCREEN,
 							G_PARAM_READWRITE));
 
+  /**
+   * IdoTimeline::started:
+   * @timeline: The #IdoTimeline emitting the signal.
+   * 
+   * The ::started signal is emitted when the timeline starts.
+   */
   signals[STARTED] =
     g_signal_new ("started",
 		  G_TYPE_FROM_CLASS (object_class),
@@ -141,6 +147,12 @@ ido_timeline_class_init (IdoTimelineClass *klass)
 		  g_cclosure_marshal_VOID__VOID,
 		  G_TYPE_NONE, 0);
 
+  /**
+   * IdoTimeline::paused:
+   * @timeline: The #IdoTimeline emitting the signal.
+   * 
+   * The ::paused signal is emitted when the timeline pauses.
+   */
   signals[PAUSED] =
     g_signal_new ("paused",
 		  G_TYPE_FROM_CLASS (object_class),
@@ -150,6 +162,12 @@ ido_timeline_class_init (IdoTimelineClass *klass)
 		  g_cclosure_marshal_VOID__VOID,
 		  G_TYPE_NONE, 0);
 
+  /**
+   * IdoTimeline::finished:
+   * @timeline: The #IdoTimeline emitting the signal.
+   * 
+   * The ::paused signal is emitted when the timeline finishes.
+   */
   signals[FINISHED] =
     g_signal_new ("finished",
 		  G_TYPE_FROM_CLASS (object_class),
@@ -159,6 +177,13 @@ ido_timeline_class_init (IdoTimelineClass *klass)
 		  g_cclosure_marshal_VOID__VOID,
 		  G_TYPE_NONE, 0);
 
+  /**
+   * IdoTimeline::frame:
+   * @timeline: The #IdoTimeline emitting the signal.
+   * @progress: The progress position for this frame from 0.0 (start) to 1.0 (end).
+   * 
+   * The ::frame signal is emitted when a frame should be drawn.
+   */
   signals[FRAME] =
     g_signal_new ("frame",
 		  G_TYPE_FROM_CLASS (object_class),
@@ -342,6 +367,15 @@ ido_timeline_new (guint duration)
 		       NULL);
 }
 
+/**
+ * ido_timeline_new_for_screen:
+ * @duration: duration in milliseconds for the timeline
+ * @screen: Screen to start on.
+ *
+ * Creates a new #IdoTimeline with the specified number of frames on the given screen.
+ *
+ * Return Value: the newly created #IdoTimeline
+ **/
 IdoTimeline *
 ido_timeline_new_for_screen (guint      duration,
                              GdkScreen *screen)
@@ -573,6 +607,13 @@ ido_timeline_set_loop (IdoTimeline *timeline,
     }
 }
 
+/**
+ * ido_timeline_set_duration:
+ * @timeline: A #IdoTimeline
+ * @duration: Duration in milliseconds.
+ *
+ * Set the animation duration.
+ */
 void
 ido_timeline_set_duration (IdoTimeline *timeline,
                            guint        duration)
@@ -590,6 +631,14 @@ ido_timeline_set_duration (IdoTimeline *timeline,
     }
 }
 
+/**
+ * ido_timeline_get_duration:
+ * @timeline: A #IdoTimeline
+ *
+ * Set the animation duration.
+ *
+ * Return Value: Duration in milliseconds.
+ */
 guint
 ido_timeline_get_duration (IdoTimeline *timeline)
 {
@@ -645,6 +694,13 @@ ido_timeline_get_direction (IdoTimeline *timeline)
   return priv->direction;
 }
 
+/**
+ * ido_timeline_set_screen:
+ * @timeline: A #IdoTimeline
+ * @screen: A #GdkScreen to use
+ *
+ * Set the screen the timeline is running on.
+ */
 void
 ido_timeline_set_screen (IdoTimeline *timeline,
                          GdkScreen   *screen)
@@ -664,6 +720,14 @@ ido_timeline_set_screen (IdoTimeline *timeline,
   g_object_notify (G_OBJECT (timeline), "screen");
 }
 
+/**
+ * ido_timeline_get_screen:
+ * @timeline: A #IdoTimeline
+ * 
+ * Get the screen this timeline is running on.
+ *
+ * Return Value: (transfer none): The #GdkScreen this timeline is running on.
+ */
 GdkScreen *
 ido_timeline_get_screen (IdoTimeline *timeline)
 {
@@ -675,6 +739,14 @@ ido_timeline_get_screen (IdoTimeline *timeline)
   return priv->screen;
 }
 
+/**
+ * ido_timeline_get_progress:
+ * @timeline: A #IdoTimeline
+ *
+ * Get the progress on the timeline.
+ *
+ * Return Value: The progress from 0.0 (start) to 1.0 (end)
+ */
 gdouble
 ido_timeline_get_progress (IdoTimeline *timeline)
 {
@@ -686,6 +758,13 @@ ido_timeline_get_progress (IdoTimeline *timeline)
   return priv->progress;
 }
 
+/**
+ * ido_timeline_set_progress:
+ * @timeline: A #IdoTimeline
+ * @progress: The progress from 0.0 (start) to 1.0 (end)
+ *
+ * Set the progress on the timeline.
+ */
 void
 ido_timeline_set_progress (IdoTimeline *timeline, gdouble progress)
 {
@@ -707,6 +786,15 @@ ido_timeline_set_progress (IdoTimeline *timeline, gdouble progress)
   ido_timeline_start (timeline);
 }
 
+/**
+ * ido_timeline_calculate_progress:
+ * @linear_progress: The progress from 0.0 (start) to 1.0 (end)
+ * @progress_type: The progress transform to apply
+ *
+ * Transform a linear progress position using the given transform.
+ *
+ * Return Value: the progress position using the provided transform.
+ */
 gdouble
 ido_timeline_calculate_progress (gdouble                 linear_progress,
                                  IdoTimelineProgressType progress_type)