From 4f0df14792093848d473d44f0a8db79046b62092 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 27 May 2010 16:33:38 -0500 Subject: Trying to document the array type and a couple closure parameters --- libdbusmenu-glib/menuitem.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/libdbusmenu-glib/menuitem.c b/libdbusmenu-glib/menuitem.c index 6a3c4bc..93c7d38 100644 --- a/libdbusmenu-glib/menuitem.c +++ b/libdbusmenu-glib/menuitem.c @@ -1199,7 +1199,7 @@ dbusmenu_menuitem_get_root (DbusmenuMenuitem * mi) /** dbusmenu_menuitem_buildxml: @mi: #DbusmenuMenuitem to represent in XML - @array: A list of string that will be turned into an XML file + @array: (element-type utf8): A list of string that will be turned into an XML file This function will add strings to the array @array. It will put at least one entry if this menu item has no children. If it has @@ -1247,7 +1247,7 @@ foreach_helper (gpointer data, gpointer user_data) dbusmenu_menuitem_foreach: @mi: The #DbusmenItem to start from @func: Function to call on every node in the tree - @data: User data to pass to the function + @data: (closure): User data to pass to the function This calls the function @func on this menu item and all of the children of this item. And their children. And @@ -1305,7 +1305,7 @@ dbusmenu_menuitem_handle_event (DbusmenuMenuitem * mi, const gchar * name, const dbusmenu_menuitem_send_about_to_show: @mi: The #DbusmenuMenuitem to send the signal on. @cb: Callback to call when the call has returned. - @cb_data: Data to pass to the callback. + @cb_data: (closure): Data to pass to the callback. This function is used to send the even that the submenu of this item is about to be shown. Callers to this event -- cgit v1.2.3 From 73419da95d0dd08aa0075b95a203d713174f698a Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 27 May 2010 22:25:28 -0500 Subject: Breaking out the buildxml function into it's own type for annotations --- libdbusmenu-glib/menuitem.h | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/libdbusmenu-glib/menuitem.h b/libdbusmenu-glib/menuitem.h index e5b5ae2..6eaed02 100644 --- a/libdbusmenu-glib/menuitem.h +++ b/libdbusmenu-glib/menuitem.h @@ -94,6 +94,15 @@ struct _DbusmenuMenuitem */ typedef void (*dbusmenu_menuitem_about_to_show_cb) (DbusmenuMenuitem * mi, gpointer user_data); +/** + dbusmenu_menuitem_buildxml_slot_t: + @stringarray: (inout) (transfer none) (element utf8): An array of strings + that can be combined into an XML file. + + This is the function that is called to represent this menu item + as an XML fragment. Should call it's own children. +*/ +typedef void (*dbusmenu_menuitem_buildxml_slot_t) (GPtrArray * stringarray); /** DbusmenuMenuitemClass: @@ -129,7 +138,7 @@ struct _DbusmenuMenuitemClass void (*realized) (void); /* Virtual functions */ - void (*buildxml) (GPtrArray * stringarray); + dbusmenu_menuitem_buildxml_slot_t buildxml; void (*handle_event) (DbusmenuMenuitem * mi, const gchar * name, const GValue * value, guint timestamp); void (*send_about_to_show) (DbusmenuMenuitem * mi, dbusmenu_menuitem_about_to_show_cb cb, gpointer cb_data); -- cgit v1.2.3 From 82f08075fc3166fdedb61bcaae942b1df58e856b Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 27 May 2010 22:49:57 -0500 Subject: Fixing annotations on the pointer prototypes. --- libdbusmenu-glib/menuitem.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/libdbusmenu-glib/menuitem.h b/libdbusmenu-glib/menuitem.h index 6eaed02..58f2086 100644 --- a/libdbusmenu-glib/menuitem.h +++ b/libdbusmenu-glib/menuitem.h @@ -86,8 +86,8 @@ struct _DbusmenuMenuitem /** dbusmenu_menuitem_about_to_show_cb: - @mi Menu item that should be shown - @user_data Extra user data sent with the function + @mi: Menu item that should be shown + @user_data: (closure): Extra user data sent with the function Callback prototype for a callback that is called when the menu should be shown. @@ -96,7 +96,7 @@ typedef void (*dbusmenu_menuitem_about_to_show_cb) (DbusmenuMenuitem * mi, gpoin /** dbusmenu_menuitem_buildxml_slot_t: - @stringarray: (inout) (transfer none) (element utf8): An array of strings + @stringarray: (inout) (array) (transfer none) (element utf8): An array of strings that can be combined into an XML file. This is the function that is called to represent this menu item -- cgit v1.2.3 From fe725c5e2cb09003a817731bc9c6ff73c536d79a Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 27 May 2010 23:00:26 -0500 Subject: Changing the comment style to make g-ir-scanner happy. --- libdbusmenu-glib/menuitem.h | 118 ++++++++++++++++++++++---------------------- 1 file changed, 59 insertions(+), 59 deletions(-) diff --git a/libdbusmenu-glib/menuitem.h b/libdbusmenu-glib/menuitem.h index 58f2086..fd72134 100644 --- a/libdbusmenu-glib/menuitem.h +++ b/libdbusmenu-glib/menuitem.h @@ -69,15 +69,15 @@ G_BEGIN_DECLS #define DBUSMENU_MENUITEM_ICON_NAME_BLANK "blank-icon" /** - DbusmenuMenuitem: - - This is the #GObject based object that represents a menu - item. It gets created the same on both the client and - the server side and libdbusmenu-glib does the work of making - this object model appear on both sides of DBus. Simple - really, though through updates and people coming on and off - the bus it can lead to lots of fun complex scenarios. -*/ + * DbusmenuMenuitem: + * + * This is the #GObject based object that represents a menu + * item. It gets created the same on both the client and + * the server side and libdbusmenu-glib does the work of making + * this object model appear on both sides of DBus. Simple + * really, though through updates and people coming on and off + * the bus it can lead to lots of fun complex scenarios. + */ typedef struct _DbusmenuMenuitem DbusmenuMenuitem; struct _DbusmenuMenuitem { @@ -85,45 +85,45 @@ struct _DbusmenuMenuitem }; /** - dbusmenu_menuitem_about_to_show_cb: - @mi: Menu item that should be shown - @user_data: (closure): Extra user data sent with the function - - Callback prototype for a callback that is called when the - menu should be shown. -*/ + * dbusmenu_menuitem_about_to_show_cb: + * @mi: Menu item that should be shown + * @user_data: (closure): Extra user data sent with the function + * + * Callback prototype for a callback that is called when the + * menu should be shown. + */ typedef void (*dbusmenu_menuitem_about_to_show_cb) (DbusmenuMenuitem * mi, gpointer user_data); /** - dbusmenu_menuitem_buildxml_slot_t: - @stringarray: (inout) (array) (transfer none) (element utf8): An array of strings - that can be combined into an XML file. - - This is the function that is called to represent this menu item - as an XML fragment. Should call it's own children. -*/ + * dbusmenu_menuitem_buildxml_slot_t: + * @stringarray: (inout) (array) (transfer none) (element utf8): An array of strings + * that can be combined into an XML file. + * + * This is the function that is called to represent this menu item + * as an XML fragment. Should call it's own children. + */ typedef void (*dbusmenu_menuitem_buildxml_slot_t) (GPtrArray * stringarray); /** - DbusmenuMenuitemClass: - @property_changed: Slot for #DbusmenuMenuitem::property-changed. - @item_activated: Slot for #DbusmenuMenuitem::item-activated. - @child_added: Slot for #DbusmenuMenuitem::child-added. - @child_removed: Slot for #DbusmenuMenuitem::child-removed. - @child_moved: Slot for #DbusmenuMenuitem::child-moved. - @realized: Slot for #DbusmenuMenuitem::realized. - @buildxml: Virtual function that appends the strings required - to represent this menu item in the menu XML file. - @handle_event: This function is to override how events are handled - by subclasses. Look at #dbusmenu_menuitem_handle_event for - lots of good information. - @send_about_to_show: Virtual function that notifies server that the - client is about to show a menu. - @reserved1: Reserved for future use. - @reserved2: Reserved for future use. - @reserved3: Reserved for future use. - @reserved4: Reserved for future use. -*/ + * DbusmenuMenuitemClass: + * @property_changed: Slot for #DbusmenuMenuitem::property-changed. + * @item_activated: Slot for #DbusmenuMenuitem::item-activated. + * @child_added: Slot for #DbusmenuMenuitem::child-added. + * @child_removed: Slot for #DbusmenuMenuitem::child-removed. + * @child_moved: Slot for #DbusmenuMenuitem::child-moved. + * @realized: Slot for #DbusmenuMenuitem::realized. + * @buildxml: Virtual function that appends the strings required + * to represent this menu item in the menu XML file. + * @handle_event: This function is to override how events are handled + * by subclasses. Look at #dbusmenu_menuitem_handle_event for + * lots of good information. + * @send_about_to_show: Virtual function that notifies server that the + * client is about to show a menu. + * @reserved1: Reserved for future use. + * @reserved2: Reserved for future use. + * @reserved3: Reserved for future use. + * @reserved4: Reserved for future use. + */ typedef struct _DbusmenuMenuitemClass DbusmenuMenuitemClass; struct _DbusmenuMenuitemClass { @@ -188,23 +188,23 @@ void dbusmenu_menuitem_handle_event (DbusmenuMenuitem * mi, const gchar * name, void dbusmenu_menuitem_send_about_to_show (DbusmenuMenuitem * mi, dbusmenu_menuitem_about_to_show_cb cb, gpointer cb_data); /** - SECTION:menuitem - @short_description: A lowlevel represenation of a menuitem - @stability: Unstable - @include: libdbusmenu-glib/menuitem.h - - A #DbusmenuMenuitem is the lowest level of represenation of a - single item in a menu. It gets created on the server side - and copied over to the client side where it gets rendered. As - the server starts to change it, and grow it, and do all kinds - of fun stuff that information is transfered over DBus and the - client updates it's understanding of the object model. - - Most people using either the client or the server should be - able to deal mostly with #DbusmenuMenuitem objects. These - are simple, but then they can be attached to more complex - objects and handled appropriately. -*/ + * SECTION:menuitem + * @short_description: A lowlevel represenation of a menuitem + * @stability: Unstable + * @include: libdbusmenu-glib/menuitem.h + * + * A #DbusmenuMenuitem is the lowest level of represenation of a + * single item in a menu. It gets created on the server side + * and copied over to the client side where it gets rendered. As + * the server starts to change it, and grow it, and do all kinds + * of fun stuff that information is transfered over DBus and the + * client updates it's understanding of the object model. + * + * Most people using either the client or the server should be + * able to deal mostly with #DbusmenuMenuitem objects. These + * are simple, but then they can be attached to more complex + * objects and handled appropriately. + */ G_END_DECLS -- cgit v1.2.3 From 0ad17a63cfbe3d19bd87db4901e3fdaafbd7def8 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Fri, 28 May 2010 14:18:42 -0500 Subject: Flattening out the documentation to make it so that it gets picked up by g-ir-scanner. --- libdbusmenu-glib/menuitem.h | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/libdbusmenu-glib/menuitem.h b/libdbusmenu-glib/menuitem.h index fd72134..2a7687b 100644 --- a/libdbusmenu-glib/menuitem.h +++ b/libdbusmenu-glib/menuitem.h @@ -96,8 +96,7 @@ typedef void (*dbusmenu_menuitem_about_to_show_cb) (DbusmenuMenuitem * mi, gpoin /** * dbusmenu_menuitem_buildxml_slot_t: - * @stringarray: (inout) (array) (transfer none) (element utf8): An array of strings - * that can be combined into an XML file. + * @stringarray: (inout) (array) (transfer none) (element utf8): An array of strings that can be combined into an XML file. * * This is the function that is called to represent this menu item * as an XML fragment. Should call it's own children. @@ -112,13 +111,9 @@ typedef void (*dbusmenu_menuitem_buildxml_slot_t) (GPtrArray * stringarray); * @child_removed: Slot for #DbusmenuMenuitem::child-removed. * @child_moved: Slot for #DbusmenuMenuitem::child-moved. * @realized: Slot for #DbusmenuMenuitem::realized. - * @buildxml: Virtual function that appends the strings required - * to represent this menu item in the menu XML file. - * @handle_event: This function is to override how events are handled - * by subclasses. Look at #dbusmenu_menuitem_handle_event for - * lots of good information. - * @send_about_to_show: Virtual function that notifies server that the - * client is about to show a menu. + * @buildxml: Virtual function that appends the strings required to represent this menu item in the menu XML file. + * @handle_event: This function is to override how events are handled by subclasses. Look at #dbusmenu_menuitem_handle_event for lots of good information. + * @send_about_to_show: Virtual function that notifies server that the client is about to show a menu. * @reserved1: Reserved for future use. * @reserved2: Reserved for future use. * @reserved3: Reserved for future use. -- cgit v1.2.3 From 09bdc1f04df9629cd7e9b3872c140f773edead87 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Fri, 4 Jun 2010 12:17:21 -0500 Subject: Fixing annotations, no everything is happy. --- libdbusmenu-glib/menuitem.h | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/libdbusmenu-glib/menuitem.h b/libdbusmenu-glib/menuitem.h index 2a7687b..b04bba8 100644 --- a/libdbusmenu-glib/menuitem.h +++ b/libdbusmenu-glib/menuitem.h @@ -96,12 +96,13 @@ typedef void (*dbusmenu_menuitem_about_to_show_cb) (DbusmenuMenuitem * mi, gpoin /** * dbusmenu_menuitem_buildxml_slot_t: - * @stringarray: (inout) (array) (transfer none) (element utf8): An array of strings that can be combined into an XML file. + * @mi: (in): Menu item that should be built from + * @stringarray: (inout) (transfer none) (array) (element-type utf8): An array of strings that can be combined into an XML file. * * This is the function that is called to represent this menu item * as an XML fragment. Should call it's own children. */ -typedef void (*dbusmenu_menuitem_buildxml_slot_t) (GPtrArray * stringarray); +typedef void (*dbusmenu_menuitem_buildxml_slot_t) (DbusmenuMenuitem * mi, GPtrArray* stringarray); /** * DbusmenuMenuitemClass: -- cgit v1.2.3 From a96851a88488411ef148bbdefbc61e576040ed11 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Fri, 4 Jun 2010 14:38:37 -0500 Subject: 0.3.1 --- configure.ac | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/configure.ac b/configure.ac index d6c7d51..33ad44d 100644 --- a/configure.ac +++ b/configure.ac @@ -1,11 +1,11 @@ -AC_INIT(libdbusmenu, 0.3.0, ted@canonical.com) +AC_INIT(libdbusmenu, 0.3.1, ted@canonical.com) AC_COPYRIGHT([Copyright 2009,2010 Canonical]) AC_PREREQ(2.62) AM_CONFIG_HEADER(config.h) -AM_INIT_AUTOMAKE(libdbusmenu, 0.3.0, [-Wno-portability]) +AM_INIT_AUTOMAKE(libdbusmenu, 0.3.1, [-Wno-portability]) AM_MAINTAINER_MODE -- cgit v1.2.3