Merging in the documentation branch.

1 files changed, 208 insertions, 0 deletions

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)
 {