From a8b1436ded0d74d44a414b0ab3df9334e24eb426 Mon Sep 17 00:00:00 2001
From: Ted Gould <ted@canonical.com>
Date: Wed, 28 Oct 2009 16:37:49 -0500
Subject: Adding in comments.

---
 libindicator/indicator-object.c | 66 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/libindicator/indicator-object.c b/libindicator/indicator-object.c
index 38847dd..e80c1d5 100644
--- a/libindicator/indicator-object.c
+++ b/libindicator/indicator-object.c
@@ -6,6 +6,14 @@
 #include "indicator.h"
 #include "indicator-object.h"
 
+/**
+	IndicatorObjectPrivate:
+	@label: The label representing this indicator or #NULL if none.
+	@icon: The icon representing this indicator or #NULL if none.
+	@menu: The menu representing this indicator or #NULL if none.
+
+	Private data for the object.
+*/
 typedef struct _IndicatorObjectPrivate IndicatorObjectPrivate;
 struct _IndicatorObjectPrivate {
 	GtkLabel * label;
@@ -23,6 +31,8 @@ static void indicator_object_finalize   (GObject *object);
 
 G_DEFINE_TYPE (IndicatorObject, indicator_object, G_TYPE_OBJECT);
 
+/* Setup the class and put the functions into the
+   class structure */
 static void
 indicator_object_class_init (IndicatorObjectClass *klass)
 {
@@ -36,6 +46,7 @@ indicator_object_class_init (IndicatorObjectClass *klass)
 	return;
 }
 
+/* Inititalize an instance */
 static void
 indicator_object_init (IndicatorObject *self)
 {
@@ -48,6 +59,7 @@ indicator_object_init (IndicatorObject *self)
 	return;
 }
 
+/* Unref the objects that we're holding on to. */
 static void
 indicator_object_dispose (GObject *object)
 {
@@ -72,6 +84,7 @@ indicator_object_dispose (GObject *object)
 	return;
 }
 
+/* Free memory */
 static void
 indicator_object_finalize (GObject *object)
 {
@@ -80,9 +93,22 @@ indicator_object_finalize (GObject *object)
 	return;
 }
 
+/**
+	indicator_object_new_from_file:
+	@file: Filename containing a loadable module
+
+	This function builds an #IndicatorObject using the symbols
+	that are found in @file.  The module is loaded and the
+	references are all kept by the object.  To unload the 
+	module the object must be destroyed.
+
+	Return value: A valid #IndicatorObject or #NULL if error.
+*/
 IndicatorObject *
 indicator_object_new_from_file (const gchar * file)
 {
+	/* Check to make sure the name exists and that the
+	   file itself exists */
 	if (file == NULL) {
 		g_warning("Invalid filename.");
 		return NULL;
@@ -93,6 +119,8 @@ indicator_object_new_from_file (const gchar * file)
 		return NULL;
 	}
 
+	/* Grab the g_module reference, pull it in but let's
+	   keep the symbols local to avoid conflicts. */
 	GModule * module = g_module_open(file,
                                      G_MODULE_BIND_LAZY | G_MODULE_BIND_LOCAL);
 	if(module == NULL) {
@@ -100,17 +128,23 @@ indicator_object_new_from_file (const gchar * file)
 		return NULL;
 	}
 
+	/* Look for the version function, error if not found. */
 	get_version_t lget_version = NULL;
 	if (!g_module_symbol(module, INDICATOR_GET_VERSION_S, (gpointer *)(&lget_version))) {
 		g_warning("Unable to get the symbol for getting the version.");
 		return NULL;
 	}
 
+	/* Check the version with the macro and make sure we're
+	   all talking the same language. */
 	if (!INDICATOR_VERSION_CHECK(lget_version())) {
 		g_warning("Indicator using API version '%s' we're expecting '%s'", lget_version(), INDICATOR_VERSION);
 		return NULL;
 	}
 
+	/* A this point we allocate the object, any code beyond
+	   here needs to deallocate it if we're returning in an
+	   error'd state. */
 	GObject * object = g_object_new(INDICATOR_OBJECT_TYPE, NULL);
 	IndicatorObjectPrivate * priv = INDICATOR_OBJECT_GET_PRIVATE(object);
 
@@ -171,11 +205,23 @@ indicator_object_new_from_file (const gchar * file)
 
 	return INDICATOR_OBJECT(object);
 
+	/* Error, let's drop the object and return NULL.  Sad when
+	   this happens. */
 unrefandout:
 	g_object_unref(object);
 	return NULL;
 }
 
+/**
+	indicator_object_get_label:
+	@io: An #IndicatorObject.
+
+	A function to get the label for a particular object.  This
+	function does not increase the refcount.  That's your job
+	if you want to do it.
+
+	Return value: A #GtkLabel or #NULL if unavailable.
+*/
 GtkLabel *
 indicator_object_get_label (IndicatorObject * io)
 {
@@ -184,6 +230,16 @@ indicator_object_get_label (IndicatorObject * io)
 	return priv->label;
 }
 
+/**
+	indicator_object_get_icon:
+	@io: An #IndicatorObject.
+
+	A function to get the icon for a particular object.  This
+	function does not increase the refcount.  That's your job
+	if you want to do it.
+
+	Return value: A #GtkImage or #NULL if unavailable.
+*/
 GtkImage *
 indicator_object_get_icon (IndicatorObject * io)
 {
@@ -192,6 +248,16 @@ indicator_object_get_icon (IndicatorObject * io)
 	return priv->icon;
 }
 
+/**
+	indicator_object_get_menu:
+	@io: An #IndicatorObject.
+
+	A function to get the menu for a particular object.  This
+	function does not increase the refcount.  That's your job
+	if you want to do it.
+
+	Return value: A #GtkMenu or #NULL if unavailable.
+*/
 GtkMenu *
 indicator_object_get_menu (IndicatorObject * io)
 {
-- 
cgit v1.2.3