Merging in the documentation branch.

1 files changed, 81 insertions, 0 deletions

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__ */