Adding a bunch of comments

5 files changed, 38 insertions, 3 deletions

diff --git a/libdbusmenu-glib/client-menuitem.c b/libdbusmenu-glib/client-menuitem.c
index f4dd583..833b28c 100644
--- a/libdbusmenu-glib/client-menuitem.c
+++ b/libdbusmenu-glib/client-menuitem.c
@@ -90,6 +90,7 @@ dbusmenu_client_menuitem_finalize (GObject *object)
 	return;
 }
 
+/* Creates the item and associates the client */
 DbusmenuClientMenuitem *
 dbusmenu_client_menuitem_new (gint id, DbusmenuClient * client)
 {
@@ -99,6 +100,7 @@ dbusmenu_client_menuitem_new (gint id, DbusmenuClient * client)
 	return mi;
 }
 
+/* Passes the event signal on through the client. */
 static void
 handle_event (DbusmenuMenuitem * mi, const gchar * name, const GValue * value, guint timestamp)
 {
@@ -107,6 +109,7 @@ handle_event (DbusmenuMenuitem * mi, const gchar * name, const GValue * value, g
 	return;
 }
 
+/* Passes the about to show signal on through the client. */
 static void
 send_about_to_show (DbusmenuMenuitem * mi)
 {
diff --git a/libdbusmenu-glib/client.c b/libdbusmenu-glib/client.c
index 7cf5a14..940adad 100644
--- a/libdbusmenu-glib/client.c
+++ b/libdbusmenu-glib/client.c
@@ -660,6 +660,8 @@ menuitem_call_cb (DBusGProxy * proxy, GError * error, gpointer userdata)
 	return;
 }
 
+/* Sends the event over DBus to the server on the other side
+   of the bus. */
 void
 dbusmenu_client_send_event (DbusmenuClient * client, gint id, const gchar * name, const GValue * value, guint timestamp)
 {
@@ -668,6 +670,8 @@ dbusmenu_client_send_event (DbusmenuClient * client, gint id, const gchar * name
 	return;
 }
 
+/* Reports errors and responds to update request that were a result
+   of sending the about to show signal. */
 static void
 about_to_show_cb (DBusGProxy * proxy, gboolean need_update, GError * error, gpointer userdata)
 {
@@ -683,17 +687,22 @@ about_to_show_cb (DBusGProxy * proxy, gboolean need_update, GError * error, gpoi
 	return;
 }
 
+/* Sends the about to show signal for a given id to the
+   server on the other side of DBus */
 void
 dbusmenu_client_send_about_to_show(DbusmenuClient * client, gint id)
 {
 	DbusmenuClientPrivate * priv = DBUSMENU_CLIENT_GET_PRIVATE(client);
 	org_ayatana_dbusmenu_about_to_show_async (priv->menuproxy, id, about_to_show_cb, client);
 	/*
-	FIXME: We should wait until either
+	TODO: We should ideally restrict the displaying of the menu until:
+
 	 - about_to_show_cb has been called and need_update was false
 	 - about_to_show_cb has been called, need_update was true and menu has been
 	   updated
 	 - about_to_show_cb has not been called and we already waited for 10msecs
+
+	There's not really support in GTK for doing this easily.
 	*/
 	return;
 }
diff --git a/libdbusmenu-glib/dbus-menu.xml b/libdbusmenu-glib/dbus-menu.xml
index e4f33df..e5b0efb 100644
--- a/libdbusmenu-glib/dbus-menu.xml
+++ b/libdbusmenu-glib/dbus-menu.xml
@@ -266,8 +266,20 @@ License version 3 and version 2.1 along with this program.  If not, see
 		</method>
 
 		<method name="AboutToShow">
-			<arg type="i" name="id" direction="in"></arg>
-			<arg type="b" name="needUpdate" direction="out"></arg>
+			<dox:d>
+			This is called by the applet to notify the application that it is about
+			to show the menu under the specified item.
+			</dox:d>
+			<arg type="i" name="id" direction="in">
+				<dox:d>
+				Which menu item represents the parent of the item about to be shown.
+				</dox:d>
+			</arg>
+			<arg type="b" name="needUpdate" direction="out">
+				<dox:d>
+				Whether this AboutToShow event should result in the menu being updated.
+				</dox:d>
+			</arg>
 		</method>
 
 <!-- Signals -->
diff --git a/libdbusmenu-glib/menuitem.c b/libdbusmenu-glib/menuitem.c
index 75dd9aa..f33da74 100644
--- a/libdbusmenu-glib/menuitem.c
+++ b/libdbusmenu-glib/menuitem.c
@@ -1203,6 +1203,16 @@ dbusmenu_menuitem_handle_event (DbusmenuMenuitem * mi, const gchar * name, const
 	}
 	return;
 }
+
+/**
+	dbusmenu_menuitem_send_about_to_show:
+	@mi: The #DbusmenuMenuitem to send the signal on.
+
+	This function is used to send the even that the submenu
+	of this item is about to be shown.  Callers to this event
+	should delay showing the menu until their callback is
+	called if possible.
+*/
 void
 dbusmenu_menuitem_send_about_to_show (DbusmenuMenuitem * mi)
 {
diff --git a/libdbusmenu-glib/server.c b/libdbusmenu-glib/server.c
index dd1238b..d87c024 100644
--- a/libdbusmenu-glib/server.c
+++ b/libdbusmenu-glib/server.c
@@ -579,6 +579,7 @@ _dbusmenu_server_event (DbusmenuServer * server, gint id, gchar * eventid, GValu
 	return TRUE;
 }
 
+/* Recieve the About To Show function.  Pass it to our menu item. */
 static gboolean
 _dbusmenu_server_about_to_show (DbusmenuServer * server, gint id, gboolean * need_update, GError ** error)
 {