Merging in the documentation branch.

6 files changed, 548 insertions, 6 deletions

diff --git a/libindicate/indicator-message.c b/libindicate/indicator-message.c
index 4e8ef30..9cd735a 100644
--- a/libindicate/indicator-message.c
+++ b/libindicate/indicator-message.c
@@ -85,6 +85,13 @@ indicate_indicator_message_finalize (GObject *object)
 G_OBJECT_CLASS (indicate_indicator_message_parent_class)->finalize (object);
 }
 
+/**
+	indicate_indicator_message_new:
+
+	Builds a new indicator message object using #g_object_new.
+
+	Return value: A pointer to a new #IndicateIndicatorMessage object.
+*/
 static const gchar *
 get_indicator_type (IndicateIndicator * indicator)
 {
diff --git a/libindicate/indicator-message.h b/libindicate/indicator-message.h
index 0910477..76273c6 100644
--- a/libindicate/indicator-message.h
+++ b/libindicate/indicator-message.h
@@ -47,19 +47,46 @@ G_BEGIN_DECLS
 typedef struct _IndicateIndicatorMessage      IndicateIndicatorMessage;
 typedef struct _IndicateIndicatorMessageClass IndicateIndicatorMessageClass;
 
-struct _IndicateIndicatorMessageClass
-{
-IndicateIndicatorClass parent_class;
+/**
+	IndicateIndicatorMessageClass:
+	@parent_class: Parent Class
+
+	Subclass of #IndicateIndicator with no new functions or signals.
+*/
+struct _IndicateIndicatorMessageClass {
+	IndicateIndicatorClass parent_class;
 };
 
-struct _IndicateIndicatorMessage
-{
-IndicateIndicator parent;
+/**
+	IndicateIndicatorMessage:
+
+	A class to represent indicators who's 'type' is "message".  These
+	are basically indicators that represent messages from humans to
+	humans via computers.  Things like instance messages, micro blogging
+	entries or e-mails.  All of these qualify as messages.
+
+	TODO: This should include a list of properties that are supported.
+*/
+struct _IndicateIndicatorMessage {
+	IndicateIndicator parent;
 };
 
 GType indicate_indicator_message_get_type (void);
 IndicateIndicatorMessage * indicate_indicator_message_new (void);
 
+/**
+	SECTION:indicator-message
+	@short_description: A representation of human generated messages
+	@stability: Unstable
+	@include: libindicate/indicator-message.h
+
+	The message indicators represent messages that come from humans
+	to humans using computers.  They come in all different forms with
+	various different interaction protocols, but they all want the human
+	at the computer to interact back with the human that sent the
+	message.
+*/
+
 G_END_DECLS
 
 #endif
diff --git a/libindicate/indicator.c b/libindicate/indicator.c
index dfcba67..76eb616 100644
--- a/libindicate/indicator.c
+++ b/libindicate/indicator.c
@@ -76,6 +76,14 @@ indicate_indicator_class_init (IndicateIndicatorClass * class)
 
 	gobj->finalize = indicate_indicator_finalize;
 
+	/** 
+		IndicateIndicator::display:
+		@arg0: The #IndicateIndicator object
+
+		Emitted when the user has clicked on this indicator.  In the
+		messaging indicator this would be when someone clicks on the
+		menu item for the indicator.
+	*/
 	signals[USER_DISPLAY] = g_signal_new(INDICATE_INDICATOR_SIGNAL_DISPLAY,
 	                                     G_TYPE_FROM_CLASS(class),
 	                                     G_SIGNAL_RUN_LAST,
@@ -83,6 +91,15 @@ indicate_indicator_class_init (IndicateIndicatorClass * class)
 	                                     NULL, NULL,
 	                                     g_cclosure_marshal_VOID__VOID,
 	                                     G_TYPE_NONE, 0);
+	/**
+		IndicateIndicator::hide:
+		@arg0: The #IndicateIndicator object
+
+		Emitted every time this indicator is hidden.  This
+		is mostly used by #IndicateServer.
+
+		Typically this results in an emition of #IndicateServer::indicator-removed.
+	*/
 	signals[HIDE] = g_signal_new(INDICATE_INDICATOR_SIGNAL_HIDE,
 	                                     G_TYPE_FROM_CLASS(class),
 	                                     G_SIGNAL_RUN_LAST,
@@ -90,6 +107,15 @@ indicate_indicator_class_init (IndicateIndicatorClass * class)
 	                                     NULL, NULL,
 	                                     g_cclosure_marshal_VOID__VOID,
 	                                     G_TYPE_NONE, 0);
+	/**
+		IndicateIndicator::show:
+		@arg0: The #IndicateIndicator object
+
+		Emitted every time this indicator is shown.  This
+		is mostly used by #IndicateServer.
+
+		Typically this results in an emition of #IndicateServer::indicator-added.
+	*/
 	signals[SHOW] = g_signal_new(INDICATE_INDICATOR_SIGNAL_SHOW,
 	                                     G_TYPE_FROM_CLASS(class),
 	                                     G_SIGNAL_RUN_LAST,
@@ -97,6 +123,16 @@ indicate_indicator_class_init (IndicateIndicatorClass * class)
 	                                     NULL, NULL,
 	                                     g_cclosure_marshal_VOID__VOID,
 	                                     G_TYPE_NONE, 0);
+	/**
+		IndicateIndicator::modified:
+		@arg0: The #IndicateIndicator object
+		@arg1: The name of the property that changed.
+
+		Emitted every time an indicator property is changed.
+		This is mostly used by #IndicateServer.
+
+		Typically this results in an emition of #IndicateServer::indicator-modified.
+	*/
 	signals[MODIFIED] = g_signal_new(INDICATE_INDICATOR_SIGNAL_MODIFIED,
 	                                     G_TYPE_FROM_CLASS(class),
 	                                     G_SIGNAL_RUN_LAST,
@@ -145,6 +181,21 @@ indicate_indicator_finalize (GObject * obj)
 	return;
 }
 
+/**
+	indicate_indicator_get_type:
+
+	Gets a unique #GType for the #IndicateIndicator objects.
+
+	Return value: A unique #GType value.
+*/
+
+/**
+	indicate_indicator_new:
+
+	Builds a new indicator object using g_object_new().
+
+	Return value: A pointer to a new #IndicateIndicator object.
+*/
 IndicateIndicator *
 indicate_indicator_new (void)
 {
@@ -152,6 +203,14 @@ indicate_indicator_new (void)
 	return indicator;
 }
 
+/**
+	indicate_indicator_show:
+	@indicator: a #IndicateIndicator to act on
+
+	Shows this indicator on the bus.  If the #IndicateServer that it's
+	connected to is not shown itself this function will show the server
+	as well using #indicate_server_show.
+*/
 void
 indicate_indicator_show (IndicateIndicator * indicator)
 {
@@ -171,6 +230,13 @@ indicate_indicator_show (IndicateIndicator * indicator)
 	return;
 }
 
+/**
+	indicate_indicator_hide:
+	@indicator: a #IndicateIndicator to act on
+
+	Hides the indicator from the bus.  Does not effect the
+	indicator's #IndicateServer in any way.
+*/
 void
 indicate_indicator_hide (IndicateIndicator * indicator)
 {
@@ -186,6 +252,14 @@ indicate_indicator_hide (IndicateIndicator * indicator)
 	return;
 }
 
+/**
+	indicate_indicator_is_visible:
+	@indicator: a #IndicateIndicator to act on
+
+	Checkes the visibility status of @indicator.
+
+	Return value: %TRUE if the indicator is visible else %FALSE.
+*/
 gboolean
 indicate_indicator_is_visible (IndicateIndicator * indicator)
 {
@@ -194,6 +268,15 @@ indicate_indicator_is_visible (IndicateIndicator * indicator)
 	return priv->is_visible;
 }
 
+/**
+	indicate_indicator_get_id:
+	@indicator: a #IndicateIndicator to act on
+
+	Gets the ID value of the @indicator.
+
+	Return value: The ID of the indicator.  Can not be zero.
+		Zero represents an error.
+*/
 guint
 indicate_indicator_get_id (IndicateIndicator * indicator)
 {
@@ -202,6 +285,15 @@ indicate_indicator_get_id (IndicateIndicator * indicator)
 	return priv->id;
 }
 
+/**
+	indicate_indicator_get_indicator_type:
+	@indicator: a #IndicateIndicator to act on
+
+	Returns the type of @indicator.  This is largely set by the subclass
+	that the indicator was built with and should not be free'd.
+
+	Return value: A string defining the type or NULL for no type.
+*/
 const gchar *
 indicate_indicator_get_indicator_type (IndicateIndicator * indicator)
 {
@@ -215,6 +307,14 @@ indicate_indicator_get_indicator_type (IndicateIndicator * indicator)
 	return NULL;
 }
 
+/**
+	indicate_indicator_user_display:
+	@indicator: a #IndicateIndicator to act on
+
+	Emits the #IndicateIndicator::user-display signal simliar to a user
+	clicking on @indicator over the bus.  Signal will not be sent if the
+	@indicator is not visible.
+*/
 void
 indicate_indicator_user_display (IndicateIndicator * indicator)
 {
@@ -227,6 +327,18 @@ indicate_indicator_user_display (IndicateIndicator * indicator)
 	return;
 }
 
+/**
+	indicate_indicator_set_property:
+	@indicator: a #IndicateIndicator to act on
+	@key: name of the property
+	@data: value of the property
+
+	Sets a simple string property on @indicator.  If the property
+	had previously been set it will replace it with the new value,
+	otherwise it will create the property.  This will include an
+	emition of #IndicateIndicator::modified if the property value
+	was changed.
+*/
 void
 indicate_indicator_set_property (IndicateIndicator * indicator, const gchar * key, const gchar * data)
 {
@@ -238,6 +350,17 @@ indicate_indicator_set_property (IndicateIndicator * indicator, const gchar * ke
 	return class->set_property(indicator, key, data);
 }
 
+/**
+	indicate_indicator_set_property_icon:
+	@indicator: a #IndicateIndicator to act on
+	@key: name of the property
+	@data: icon to set property with
+
+	This is a helper function that wraps around #indicate_indicator_set_property
+	but takes an #GdkPixbuf parameter.  It then takes the @data
+	parameter, turns it into a PNG, base64 encodes it and then
+	uses that data to call #indicate_indicator_set_property.
+*/
 void
 indicate_indicator_set_property_icon (IndicateIndicator * indicator, const gchar * key, const GdkPixbuf * data)
 {
@@ -271,6 +394,17 @@ indicate_indicator_set_property_icon (IndicateIndicator * indicator, const gchar
 	return;
 }
 
+/**
+	indicate_indicator_set_property_time:
+	@indicator: a #IndicateIndicator to act on
+	@key: name of the property
+	@time: time to set property with
+
+	This is a helper function that wraps around #indicate_indicator_set_property
+	but takes an #GTimeVal parameter.  It then takes the @data
+	parameter converts it to an ISO 8601 time string and
+	uses that data to call #indicate_indicator_set_property.
+*/
 void
 indicate_indicator_set_property_time (IndicateIndicator * indicator, const gchar * key, GTimeVal * time)
 {
@@ -282,6 +416,16 @@ indicate_indicator_set_property_time (IndicateIndicator * indicator, const gchar
 	return;
 }
 
+/**
+	indicate_indicator_get_property:
+	@indicator: a #IndicateIndicator to act on
+	@key: name of the property
+
+	Returns the value that is set for a property or %NULL if that
+	property is not set.
+
+	Return value: A constant string or NULL.
+*/
 const gchar *
 indicate_indicator_get_property (IndicateIndicator * indicator, const gchar * key)
 {
@@ -293,6 +437,17 @@ indicate_indicator_get_property (IndicateIndicator * indicator, const gchar * ke
 	return class->get_property(indicator, key);
 }
 
+/**
+	indicate_indicator_list_properties:
+	@indicator: a #IndicateIndicator to act on
+
+	This function gets a list of all the properties that exist
+	on a @indicator.  The array may have zero entries but almost
+	always at least has 'type' in it.
+
+	Return value: An array of strings that is the keys of all
+		the properties on this indicator.
+*/
 GPtrArray *
 indicate_indicator_list_properties (IndicateIndicator * indicator)
 {
diff --git a/libindicate/indicator.h b/libindicate/indicator.h
index 8af5568..3e2a803 100644
--- a/libindicate/indicator.h
+++ b/libindicate/indicator.h
@@ -56,10 +56,43 @@ G_BEGIN_DECLS
 typedef struct _IndicateIndicator IndicateIndicator;
 typedef struct _IndicateIndicatorClass IndicateIndicatorClass;
 
+/**
+	IndicateIndicator:
+
+	The indicator object represents a single item that is shared over the
+	indicator bus.  This could be something like one IM, one e-mail or 
+	a single system update.  It should be accessed only through its
+	accessors.
+*/
 struct _IndicateIndicator {
 	GObject parent;
 };
 
+/**
+	IndicateIndicatorClass:
+	@parent_class: Parent class #GObjectClass.
+	@hide: Slot for #IndicateIndicator::hide.
+	@show: Slot for #IndicateIndicator::show.
+	@user_display: Slot for #IndicateIndicator::user-display.
+	@modified: Slot for #IndicateIndicator::modified.
+	@get_type: Returns a constant string for the type of this indicator.
+		Typically gets overridden by subclasses and defines the type of
+		the indicator.  Is called by indicate_indicator_get_indicator_type().
+	@set_property: Called when indicate_indicator_set_property() is called
+		and should set the value.  While typically it is overridden by
+		subclasses they usually handle special properties themselves and
+		then call the superclass for storage.
+	@get_property: Called when indicate_indicator_get_property() is called
+		and should return the value requested.  Many times this is left alone.
+	@list_properties: Called when indicate_indicator_list_properties() is called
+		and returns a list of the properties available.  Again this can be
+		overridden by subclasses to handle special properties.
+
+	All of the functions that are used to modify or change data that is
+	in the indicator.  Typically gets subclassed by other types of 
+	indicators, for example #IndicateIndicatorMessages.
+
+*/
 struct _IndicateIndicatorClass {
 	GObjectClass parent_class;
 
@@ -100,6 +133,37 @@ void indicate_indicator_set_property_time (IndicateIndicator * indicator, const
 const gchar * indicate_indicator_get_property (IndicateIndicator * indicator, const gchar * key);
 GPtrArray * indicate_indicator_list_properties (IndicateIndicator * indicator);
 
+/**
+	SECTION:indicator
+	@short_description: A representation of state for applications
+	@stability: Unstable
+	@include: libindicate/indicator.h
+
+	An indicator is designed to represent a single instance of something
+	in your application.  So this might be an IM or Email using #IndicateIndicatorMessage
+	or any other thing that is a small unit of information to pass on
+	to the user.
+
+	Indicators make no promises about how they are preceived by the
+	user, it's up to the listener to represent them in an intutive and
+	visually appealling way.  But, what we can do is provide information
+	on the indicator to provide enough information for the listener
+	to do that.
+
+	Mostly this is done through properties.  The only property that is
+	defined for the base indicator is the 'type' property.  And this
+	is only available to set by creating a subclass of the 
+	#IndicateIndicator object.  It is assumed that you can look at the
+	definitions of the various subtypes to determine which properties
+	they support.
+
+	It may be that some users don't want to create objects for every
+	indicator as it could be a lot of overhead if there are large numbers
+	and there is already a data structure representing them all.  In that
+	case it is recommended that you ignore the #IndicateIndicator object
+	tree in general and move to subclassing #IndicateServer directly.
+*/
+
 G_END_DECLS
 
 #endif /* INDICATE_INDICATOR_H_INCLUDED__ */
diff --git a/libindicate/server.c b/libindicate/server.c
index d42fe61..cd8b33a 100644
--- a/libindicate/server.c
+++ b/libindicate/server.c
@@ -163,6 +163,17 @@ indicate_server_class_init (IndicateServerClass * class)
 	gobj->set_property = set_property;
 	gobj->get_property = get_property;
 
+	/**
+		IndicateServer::indicator-added:
+		@arg0: The #IndicateServer object
+		@arg1: The #IndicateIndicator ID number
+		@arg2: The type of the indicator
+
+		Emitted every time that a new indicator is made visible to
+		the world.  This results in a signal on DBus.
+
+		Can be emitted by subclasses using indicate_server_emit_indicator_added()
+	*/
 	signals[INDICATOR_ADDED] = g_signal_new(INDICATE_SERVER_SIGNAL_INDICATOR_ADDED,
 	                                        G_TYPE_FROM_CLASS (class),
 	                                        G_SIGNAL_RUN_LAST,
@@ -170,6 +181,17 @@ indicate_server_class_init (IndicateServerClass * class)
 	                                        NULL, NULL,
 	                                        g_cclosure_marshal_VOID__UINT_POINTER,
 	                                        G_TYPE_NONE, 2, G_TYPE_UINT, G_TYPE_STRING);
+	/**
+		IndicateServer::indicator-removed:
+		@arg0: The #IndicateServer object
+		@arg1: The #IndicateIndicator ID number
+		@arg2: The type of the indicator
+
+		Emitted every time that a new indicator is made invisible to
+		the world.  This results in a signal on DBus.
+
+		Can be emitted by subclasses using indicate_server_emit_indicator_removed()
+	*/
 	signals[INDICATOR_REMOVED] = g_signal_new(INDICATE_SERVER_SIGNAL_INDICATOR_REMOVED,
 	                                        G_TYPE_FROM_CLASS (class),
 	                                        G_SIGNAL_RUN_LAST,
@@ -177,6 +199,17 @@ indicate_server_class_init (IndicateServerClass * class)
 	                                        NULL, NULL,
 	                                        g_cclosure_marshal_VOID__UINT_POINTER,
 	                                        G_TYPE_NONE, 2, G_TYPE_UINT, G_TYPE_STRING);
+	/**
+		IndicateServer::indicator-modified:
+		@arg0: The #IndicateServer object
+		@arg1: The #IndicateIndicator ID number
+		@arg2: The name of the property modified
+
+		Emitted every time that a property on an indicator changes
+		and it is visible to the world.  This results in a signal on DBus.
+
+		Can be emitted by subclasses using indicate_server_emit_indicator_modified()
+	*/
 	signals[INDICATOR_MODIFIED] = g_signal_new(INDICATE_SERVER_SIGNAL_INDICATOR_MODIFIED,
 	                                        G_TYPE_FROM_CLASS (class),
 	                                        G_SIGNAL_RUN_LAST,
@@ -184,6 +217,15 @@ indicate_server_class_init (IndicateServerClass * class)
 	                                        NULL, NULL,
 	                                        g_cclosure_marshal_VOID__UINT_POINTER,
 	                                        G_TYPE_NONE, 2, G_TYPE_UINT, G_TYPE_STRING);
+	/**
+		IndicateServer::server-show:
+		@arg0: The #IndicateServer object
+		@arg1: The type of the server
+
+		Emitted when a server comes onto DBus by being shown.  This
+		is typically when listeners start reacting to the application's
+		indicators.  This results in a signal on DBus.
+	*/
 	signals[SERVER_SHOW] = g_signal_new(INDICATE_SERVER_SIGNAL_SERVER_SHOW,
 	                                        G_TYPE_FROM_CLASS (class),
 	                                        G_SIGNAL_RUN_LAST,
@@ -191,6 +233,14 @@ indicate_server_class_init (IndicateServerClass * class)
 	                                        NULL, NULL,
 	                                        g_cclosure_marshal_VOID__POINTER,
 	                                        G_TYPE_NONE, 1, G_TYPE_STRING);
+	/**
+		IndicateServer::server-hide:
+		@arg0: The #IndicateServer object
+		@arg1: The type of the server
+
+		Emitted when a server removes itself from DBus.  This results
+		in a signal on DBus.
+	*/
 	signals[SERVER_HIDE] = g_signal_new(INDICATE_SERVER_SIGNAL_SERVER_HIDE,
 	                                        G_TYPE_FROM_CLASS (class),
 	                                        G_SIGNAL_RUN_LAST,
@@ -198,6 +248,16 @@ indicate_server_class_init (IndicateServerClass * class)
 	                                        NULL, NULL,
 	                                        g_cclosure_marshal_VOID__POINTER,
 	                                        G_TYPE_NONE, 1, G_TYPE_STRING);
+	/**
+		IndicateServer::server-display:
+		@arg0: The #IndicateServer object
+
+		Emitted when a listener signals that the server itself should be
+		displayed.  This signal is caused by a user clicking on the application
+		item in the Messaging Menu.  This signal is emitted by DBus.
+
+		Can be emitted by subclasses using indicate_server_emit_server_display()
+	*/
 	signals[SERVER_DISPLAY] = g_signal_new(INDICATE_SERVER_SIGNAL_SERVER_DISPLAY,
 	                                        G_TYPE_FROM_CLASS (class),
 	                                        G_SIGNAL_RUN_LAST,
@@ -205,6 +265,14 @@ indicate_server_class_init (IndicateServerClass * class)
 	                                        NULL, NULL,
 	                                        g_cclosure_marshal_VOID__VOID,
 	                                        G_TYPE_NONE, 0);
+	/**
+		IndicateServer::interest-added:
+		@arg0: The #IndicateServer object
+		@arg1: The interest that was added from #IndicateInterests
+
+		Emitted when a listener signals that they are interested in
+		this server for a particular reason.  This signal is emitted by DBus.
+	*/
 	signals[INTEREST_ADDED] = g_signal_new(INDICATE_SERVER_SIGNAL_INTEREST_ADDED,
 	                                        G_TYPE_FROM_CLASS (class),
 	                                        G_SIGNAL_RUN_LAST,
@@ -212,6 +280,14 @@ indicate_server_class_init (IndicateServerClass * class)
 	                                        NULL, NULL,
 	                                        g_cclosure_marshal_VOID__UINT,
 	                                        G_TYPE_NONE, 1, G_TYPE_UINT);
+	/**
+		IndicateServer::interest-removed:
+		@arg0: The #IndicateServer object
+		@arg1: The interest that was removed from #IndicateInterests
+
+		Emitted when a listener signals that they are no longer interested in
+		this server for a particular reason.  This signal is emitted by DBus.
+	*/
 	signals[INTEREST_REMOVED] = g_signal_new(INDICATE_SERVER_SIGNAL_INTEREST_REMOVED,
 	                                        G_TYPE_FROM_CLASS (class),
 	                                        G_SIGNAL_RUN_LAST,
@@ -366,7 +442,17 @@ indicate_server_error_quark (void)
 	return quark;
 }
 
+/**
+	indicate_server_show:
+	@server: The #IndicateServer to be shown
 
+	This function exports the object onto DBus and shows it
+	to the world.  This will be the start of it receiving external
+	signals from DBus.  It is likely that, if there are listeners
+	running, there will several #IndicateServer::interest-added
+	signals coming shortly after this function.  This function
+	emits the #IndicateServer::server-added signal across the bus.
+*/
 void
 indicate_server_show (IndicateServer * server)
 {
@@ -403,6 +489,16 @@ indicate_server_show (IndicateServer * server)
 	return;
 }
 
+/**
+	indicate_server_hide:
+	@server: The #IndicateServer to hide.
+
+	This function hides the server from DBus so that it does
+	not get signals anymore.  This causes the signal #IndicateServer::server-hide
+	to be sent across the bus for all listeners.  Also internally
+	it will signal #IndicateServer::interest-removed for all the
+	interests that were currently set for this server.
+*/
 void
 indicate_server_hide (IndicateServer * server)
 {
@@ -610,6 +706,16 @@ indicator_modified_cb (IndicateIndicator * indicator, gchar * property, Indicate
 	g_signal_emit(server, signals[INDICATOR_MODIFIED], 0, indicate_indicator_get_id(indicator), property, TRUE);
 }
 
+/**
+	indicate_server_add_indicator:
+	@server: The #IndicateServer to add the #IndicateIndictor to.
+	@indicator: The #IndicateIndicator to add.
+
+	This function adds an indicator @indicator to the list that are
+	watched by the server @server.  This means that signals that are
+	emitted by the indicator will be picked up and passed via DBus onto
+	listeners of the application.
+*/
 void
 indicate_server_add_indicator (IndicateServer * server, IndicateIndicator * indicator)
 {
@@ -633,6 +739,14 @@ indicate_server_add_indicator (IndicateServer * server, IndicateIndicator * indi
 	return;
 }
 
+/**
+	indicate_server_remove_indicator:
+	@server: The #IndicateServer to remove the #IndicateIndictor from.
+	@indicator: The #IndicateIndicator to remove.
+
+	Removes an indicator @indicator from being watched by the server @server
+	so it's signals are no longer watched and set over DBus.
+*/
 void
 indicate_server_remove_indicator (IndicateServer * server, IndicateIndicator * indicator)
 {
@@ -663,6 +777,15 @@ indicate_server_set_dbus_object (const gchar * obj)
 	return;
 }
 
+/**
+	indicate_server_set_desktop_file:
+	@server: The #IndicateServer to set the type of
+	@path: The new desktop file representing the server
+
+	This is a convience function to set the #IndicateServer:desktop
+	property of the @server object.  The property can also be set
+	via traditional means, but this one is easier to read.
+*/
 void
 indicate_server_set_desktop_file (IndicateServer * server, const gchar * path)
 {
@@ -673,6 +796,15 @@ indicate_server_set_desktop_file (IndicateServer * server, const gchar * path)
 	return;
 }
 
+/**
+	indicate_server_set_type:
+	@server: The #IndicateServer to set the type of
+	@type: The new type of the server
+
+	This is a convience function to set the #IndicateServer:type
+	property of the @server object.  The property can also be set
+	via traditional means, but this one is easier to read.
+*/
 void
 indicate_server_set_type (IndicateServer * server, const gchar * type)
 {
@@ -685,6 +817,17 @@ indicate_server_set_type (IndicateServer * server, const gchar * type)
 
 static IndicateServer * default_indicate_server = NULL;
 
+/**
+	indicate_server_ref_default:
+
+	This function will return a reference to the default #IndicateServer
+	reference if there is one, or it will create one if one had not
+	previously been created.  It is recommended that all applications
+	use this function to create a #IndicateServer as it ensure that there
+	is only one per application.
+
+	Return value: A reference to the default #IndicateServer instance.
+*/
 IndicateServer *
 indicate_server_ref_default (void)
 {
@@ -699,6 +842,16 @@ indicate_server_ref_default (void)
 	return default_indicate_server;
 }
 
+/**
+	indicate_server_set_default:
+	@server: The #IndicateServer that should be used
+
+	This function is used to set the default #IndicateServer that will
+	be used when creating #IndicateIndicators or for anyone else that
+	calls indicate_server_ref_default().  Typically this is just an
+	instance of #IndicateServer but applications that create a subclass
+	of #IndicateServer should set this as well.
+*/
 void
 indicate_server_set_default (IndicateServer * server)
 {
@@ -1103,6 +1256,15 @@ _indicate_server_show_indicator_to_user (IndicateServer * server, guint id, GErr
 	return TRUE;
 }
 
+/**
+	indicate_server_get_next_id:
+	@server: The #IndicateServer the ID will be on
+
+	Returns the next available unused ID that an indicator
+	can have.
+
+	Return value: A valid indicator ID.
+*/
 guint 
 indicate_server_get_next_id (IndicateServer * server)
 {
@@ -1207,6 +1369,17 @@ _indicate_server_remove_interest (IndicateServer * server, gchar * interest, DBu
 	return FALSE;
 }
 
+/**
+	indicate_server_check_interest:
+	@server: The #IndicateServer being checked
+	@interest: Which interest type we're checking for
+
+	This function looks at all the interest that various listeners
+	have specified that they have for this server and returns whether
+	there is a listener that has the interest specified in @interest.
+
+	Return value: %TRUE if a listener as the interest otherwise %FALSE
+*/
 gboolean
 indicate_server_check_interest (IndicateServer * server, IndicateInterests interest)
 {
@@ -1221,6 +1394,16 @@ indicate_server_check_interest (IndicateServer * server, IndicateInterests inter
 }
 
 /* Signal emission functions for sub-classes of the server */
+
+/**
+	indicate_server_emit_indicator_added:
+	@server: The #IndicateServer being represented
+	@id: The ID of the indicator being added
+	@type: The type of the indicator
+
+	This function emits the #IndicateServer::indicator-added signal and is
+	used by subclasses.
+*/
 void 
 indicate_server_emit_indicator_added (IndicateServer *server, guint id, const gchar *type)
 {
@@ -1230,6 +1413,15 @@ indicate_server_emit_indicator_added (IndicateServer *server, guint id, const gc
   g_signal_emit(server, signals[INDICATOR_ADDED], 0, id, type);
 }
 
+/**
+	indicate_server_emit_indicator_removed:
+	@server: The #IndicateServer being represented
+	@id: The ID of the indicator being removed
+	@type: The type of the indicator
+
+	This function emits the #IndicateServer::indicator-removed signal and is
+	used by subclasses.
+*/
 void 
 indicate_server_emit_indicator_removed (IndicateServer *server, guint id, const gchar *type)
 {
@@ -1239,6 +1431,15 @@ indicate_server_emit_indicator_removed (IndicateServer *server, guint id, const
   g_signal_emit(server, signals[INDICATOR_REMOVED], 0, id, type);
 }
 
+/**
+	indicate_server_emit_indicator_modified:
+	@server: The #IndicateServer being represented
+	@id: The ID of the indicator with the modified property
+	@property: The name of the property being modified
+
+	This function emits the #IndicateServer::indicator-modified signal and is
+	used by subclasses.
+*/
 void 
 indicate_server_emit_indicator_modified (IndicateServer *server, guint id, const gchar *property)
 {
@@ -1248,6 +1449,13 @@ indicate_server_emit_indicator_modified (IndicateServer *server, guint id, const
   g_signal_emit(server, signals[INDICATOR_MODIFIED], 0, id, property);
 }
 
+/**
+	indicate_server_emit_server_display:
+	@server: The #IndicateServer being displayed
+
+	This function emits the #IndicateServer::server-display signal and is
+	used by subclasses.
+*/
 void 
 indicate_server_emit_server_display (IndicateServer *server)
 {
diff --git a/libindicate/server.h b/libindicate/server.h
index cfb4334..2a300e2 100644
--- a/libindicate/server.h
+++ b/libindicate/server.h
@@ -57,11 +57,63 @@ G_BEGIN_DECLS
 #define INDICATE_SERVER_SIGNAL_INTEREST_ADDED       "interest-added"
 #define INDICATE_SERVER_SIGNAL_INTEREST_REMOVED     "interest-removed"
 
+/**
+	IndicateServer:
+
+	This is the object that represents the overall connection
+	between this application and DBus.  It acts as the proxy for
+	incomming DBus calls and also sends the appropriate signals
+	on DBus for events happening on other objects locally.  It
+	provides some settings that effection how the application as
+	a whole is perceived by listeners of the indicator protocol.
+*/
 typedef struct _IndicateServer IndicateServer;
 struct _IndicateServer {
 	GObject parent;
 };
 
+/**
+	IndicateServerClass:
+	@parent: Parent Class
+	@indicator_added: Slot for #IndicateServer::indicator-added.
+	@indicator_removed: Slot for #IndicateServer::indicator-removed.
+	@indicator_modified: Slot for #IndicateServer::indicator-modified.
+	@server_show: Slot for #IndicateServer::server-show.
+	@server_hide: Slot for #IndicateServer::server-hide.
+	@server_display: Slot for #IndicateServer::server-display.
+	@interest_added: Slot for #IndicateServer::interest-added.
+	@interest_removed: Slot for #IndicateServer::interest-removed.
+	@get_indicator_count: Returns the number of indicators that are visible
+		on the bus.  Hidden indicators should not be counted.
+	@get_indicator_count_by_type: Returns the number of indicators that are
+		of a given type and visible on the bus.
+	@get_indicator_list: List all of the indicators that are visible.
+	@get_indicator_list_by_type: List all of the indicators of a given
+		type that are visible.
+	@get_indicator_property: Get a property from a particular indicator.
+	@get_indicator_property_group: Get the values for a set of properties
+		as an array of entries, returning an array as well.
+	@get_indicator_properties: Get a list of all the properties that are
+		on a particular indicator.
+	@show_indicator_to_user: Respond to someone on the bus asking to show
+		a particular indicator to the user.
+	@get_next_id: Get the next unused indicator ID.
+	@show_interest: React to someone signifying that they are interested
+		in this server.
+	@remove_interest: Someone on the bus is no longer interest in this
+		server, remove it's interest.
+	@check_interest: Check to see if anyone on the bus is interested in this
+		server for a particular feature.
+	@indicate_server_reserved1: Reserved for future use
+	@indicate_server_reserved2: Reserved for future use
+	@indicate_server_reserved3: Reserved for future use
+	@indicate_server_reserved4: Reserved for future use
+
+	All of the functions and signals that make up the server class
+	including those that are public API to the application and those
+	that are public API to all of DBus.  Subclasses may need to
+	implement a large portion of these.
+*/
 typedef struct _IndicateServerClass IndicateServerClass;
 struct _IndicateServerClass {
 	GObjectClass parent;
@@ -134,6 +186,35 @@ void indicate_server_emit_indicator_removed (IndicateServer *server, guint id, c
 void indicate_server_emit_indicator_modified (IndicateServer *server, guint id, const gchar *property);
 void indicate_server_emit_server_display (IndicateServer *server);
 
+/**
+	SECTION:server
+	@short_description: The representation of the application on DBus.
+	@stability: Unstable
+	@include: libindicate/server.h
+
+	The server object is the object that provides the functions on
+	to DBus for other applications to call.  It does this by implementing
+	the DBus indicator spec, but it also allows for subclassing so that
+	subclasses don't have to worry about the DBus-isms as much as
+	the functionality that they're trying to express.
+
+	For simple applications there is limited need to set anything
+	more than the desktop file and the type of the server using
+	indicate_server_set_desktop_file() and indicate_server_set_type().
+	Each of these function sets the respective value and expresses
+	it in a way that other applications on the bus can read it.
+
+	More advanced applications might find the need to subclass the
+	#IndicateServer object and make their own.  This is likely the
+	case where applications have complex data stores that they don't
+	want to turn into a large set of #GObjects that can take up a
+	significant amount of memory in the program.
+
+	In general, it is recommended that application authors go with
+	the high memory path first, and then optimize by implementing
+	their server on a second pass.
+*/
+
 G_END_DECLS
 
 #endif /* INDICATE_SERVER_H_INCLUDED__ */