Merge lp:~robert-ancell/ido/lp582985 into lp:ido/13.04

[Robert Ancell]

Add introspection and vala support

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:121
http://jenkins.qa.ubuntu.com/job/ido-ci/18/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/ido-ci/./build=pbuilder,distribution=coverity-raring,flavor=amd64/18/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ido-ci/./build=pbuilder,distribution=raring,flavor=i386/18/console

Click here to trigger a rebuild:
http://jenkins.qa.ubuntu.com/job/ido-ci/18//rebuild/?

review: Needs Fixing (continuous-integration)

[Robert Ancell (robert-ancell)]

I think the build failure might be because the packaging branch that Jenkins is using won't have the dependencies required for this? I can update the packaging but not sure where it is...

[Mathieu Trudel-Lapierre (cyphermox)]

Correct, given that we now use "inline" packaging (split mode in bzr), you'll want to add gobject-introspection to the build-depends.

review: Needs Fixing

[Robert Ancell (robert-ancell)]

Whoops, I was looking at libindicate. Now I notice debian/ is in ido. Too many i* names...

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:122
http://jenkins.qa.ubuntu.com/job/ido-ci/19/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/ido-ci/./build=pbuilder,distribution=raring,flavor=amd64/19/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/ido-ci/./build=pbuilder,distribution=raring,flavor=i386/19/console

Click here to trigger a rebuild:
http://jenkins.qa.ubuntu.com/job/ido-ci/19//rebuild/?

review: Needs Fixing (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:123
http://jenkins.qa.ubuntu.com/job/ido-ci/20/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/ido-ci/./build=pbuilder,distribution=raring,flavor=amd64/20/console
    SUCCESS: http://jenkins.qa.ubuntu.com/job/ido-ci/./build=pbuilder,distribution=raring,flavor=i386/20/console

Click here to trigger a rebuild:
http://jenkins.qa.ubuntu.com/job/ido-ci/20//rebuild/?

review: Needs Fixing (continuous-integration)

[Robert Ancell (robert-ancell)]

Hmm, the amd64 build failure seems to be something to do with Xvfb? I can't trigger a rebuild it seems, can someone?

[Allan LeSage (allanlesage)]

Let me do a test build Robert, will report here.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:123
http://jenkins.qa.ubuntu.com/job/ido-ci/23/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/ido-ci/./build=pbuilder,distribution=raring,flavor=amd64/23/console
    SUCCESS: http://jenkins.qa.ubuntu.com/job/ido-ci/./build=pbuilder,distribution=raring,flavor=i386/23/console

Click here to trigger a rebuild:
http://jenkins.qa.ubuntu.com/job/ido-ci/23//rebuild/?

review: Approve (continuous-integration)

[Allan LeSage (allanlesage)]

Fixed the tests separately (in https://code.launchpad.net/~allanlesage/ido/remove-Xvfb-auto-test-override/+merge/140307).

[Robert Ancell (robert-ancell)]

Thanks Allan!

[Mathieu Trudel-Lapierre (cyphermox)]

Approve

review: Approve

[PS Jenkins bot (ps-jenkins)]

FAILED: Autolanding.
No commit message was specified.

review: Needs Fixing (continuous-integration)

[Allan LeSage (allanlesage)]

The "use description for commit" option was set for this build--attempting again.

[PS Jenkins bot (ps-jenkins)]

FAILED: Autolanding.
No commit message was specified.

review: Needs Fixing (continuous-integration)

=== modified file 'configure.ac'
--- configure.ac	2012-11-08 15:37:00 +0000
+++ configure.ac	2012-12-15 07:41:19 +0000
@@ -123,6 +123,14 @@
 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 " Prefix       : ${prefix}"
 echo " gcov         : ${use_gcov}"
+echo " introspection: ${enable_introspection}"
 echo ""
 echo " Documentation: ${enable_gtk_doc}"
 echo ""
 
=== modified file 'debian/control'
--- debian/control	2012-12-05 15:40:53 +0000
+++ debian/control	2012-12-15 07:41:19 +0000
@@ -11,6 +11,11 @@
                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
@@ -44,3 +49,15 @@
  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.
 
=== added file 'debian/gir1.2-ido3-0.1.install'
--- debian/gir1.2-ido3-0.1.install	1970-01-01 00:00:00 +0000
+++ debian/gir1.2-ido3-0.1.install	2012-12-15 07:41:19 +0000
@@ -0,0 +1,1 @@
+usr/lib/*/girepository-1.0 /usr/lib
 
=== modified file 'debian/libido3-0.1-dev.install'
--- debian/libido3-0.1-dev.install	2012-11-19 18:58:43 +0000
+++ debian/libido3-0.1-dev.install	2012-12-15 07:41:19 +0000
@@ -1,3 +1,5 @@
 usr/include/libido3-*
 usr/lib/*/pkgconfig/libido3-*
 usr/lib/*/libido3-*.so
+usr/share/vala
+usr/share/gir-1.0
 
=== modified file 'src/Makefile.am'
--- src/Makefile.am	2012-08-22 14:39:22 +0000
+++ src/Makefile.am	2012-12-15 07:41:19 +0000
@@ -1,3 +1,5 @@
+CLEANFILES =
+
 VER=3
 lib_LTLIBRARIES = libido3-0.1.la
 
@@ -94,3 +96,54 @@
 	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
 
=== modified file 'src/idocalendarmenuitem.c'
--- src/idocalendarmenuitem.c	2012-09-20 04:32:58 +0000
+++ src/idocalendarmenuitem.c	2012-12-15 07:41:19 +0000
@@ -324,21 +324,44 @@
   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 @@
   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 @@
   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 @@
   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 @@
   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 @@
   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 @@
   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 @@
   gtk_calendar_select_day (GTK_CALENDAR (menuitem->priv->calendar), day);
   return TRUE;
 }
-
-
-
 
=== modified file 'src/idoentrymenuitem.c'
--- src/idoentrymenuitem.c	2012-08-22 14:41:36 +0000
+++ src/idoentrymenuitem.c	2012-12-15 07:41:19 +0000
@@ -260,17 +260,31 @@
                          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;
 }
 
=== modified file 'src/idomessagedialog.c'
--- src/idomessagedialog.c	2012-08-22 14:44:00 +0000
+++ src/idomessagedialog.c	2012-12-15 07:41:19 +0000
@@ -258,7 +258,7 @@
  * 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 @@
   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,
 
=== modified file 'src/idorange.c'
--- src/idorange.c	2012-08-27 20:01:07 +0000
+++ src/idorange.c	2012-12-15 07:41:19 +0000
@@ -172,6 +172,8 @@
  * @style: The range style
  *
  * Creates a new #IdoRange widget.
+ *
+ * Return Value: A new #IdoRange
  **/
 GtkWidget *
 ido_range_new (GObject *adj,
 
=== modified file 'src/idoscalemenuitem.c'
--- src/idoscalemenuitem.c	2012-08-27 20:01:07 +0000
+++ src/idoscalemenuitem.c	2012-12-15 07:41:19 +0000
@@ -309,6 +309,12 @@
                                                          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 @@
                                           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 @@
                                            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 @@
                                            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 @@
  * @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 @@
  * @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_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_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 @@
   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_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_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_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:
+ * 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_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:
+ * 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_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 @@
 }
 
 /**
- * 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)
 
=== modified file 'src/idoscalemenuitem.h'
--- src/idoscalemenuitem.h	2012-03-10 06:04:36 +0000
+++ src/idoscalemenuitem.h	2012-12-15 07:41:19 +0000
@@ -61,8 +61,8 @@
   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);
 };
 
 
 
=== modified file 'src/idoswitchmenuitem.c'
--- src/idoswitchmenuitem.c	2012-08-21 21:43:49 +0000
+++ src/idoswitchmenuitem.c	2012-12-15 07:41:19 +0000
@@ -101,16 +101,27 @@
   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)
 {
 
=== modified file 'src/idotimeline.c'
--- src/idotimeline.c	2011-06-01 19:36:43 +0000
+++ src/idotimeline.c	2012-12-15 07:41:19 +0000
@@ -132,6 +132,12 @@
 							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 @@
 		  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 @@
 		  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 @@
 		  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 @@
 		       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_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_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 @@
   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 @@
   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 @@
   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 @@
   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_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)