[seahorse/be9ddd5: 8/8] Full documentation for seahorse-dns-sd.c

[Thorsten Sick <tsick src gnome org>]

commit be9ddd5ac9df75223db55982ff843eaccc753dea
Author: Thorsten Sick <tsick src gnome org>
Date:   Sat Jan 9 13:19:58 2010 +0100

    Full documentation for seahorse-dns-sd.c
    
    This patch adds full documentation for seahorse-dns-sd.c.
    Static functions are commented in a non-specific way, the other functions in a GTK-Doc style.

 libseahorse/seahorse-dns-sd.c |  120 ++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 119 insertions(+), 1 deletions(-)
---
diff --git a/libseahorse/seahorse-dns-sd.c b/libseahorse/seahorse-dns-sd.c
index 3cd7625..d38a8b9 100644
--- a/libseahorse/seahorse-dns-sd.c
+++ b/libseahorse/seahorse-dns-sd.c
@@ -38,6 +38,13 @@
 /* Override the DEBUG_DNSSD_ENABLE switch here */
 /* #define DEBUG_DNSSD_ENABLE 1 */
 
+/**
+ * SECTION:seahorse-dns-sd
+ * @short_description: This file contains functions to connect to Avahi services.
+ * @include:seahorse-dns-sd.h
+ *
+ **/
+
 #ifndef DEBUG_DNSSD_ENABLE
 #if _DEBUG
 #define DEBUG_DNSSD_ENABLE 1
@@ -85,6 +92,12 @@ G_DEFINE_TYPE (SeahorseServiceDiscovery, seahorse_service_discovery, G_TYPE_OBJE
 
 #ifdef WITH_SHARING
 
+/**
+* ssd: SeahorseServiceDiscovery structure
+*
+* Disconnects the Avahi browser and client in the ssd structure
+*
+**/
 static void
 disconnect (SeahorseServiceDiscovery *ssd)
 {
@@ -97,6 +110,24 @@ disconnect (SeahorseServiceDiscovery *ssd)
     ssd->priv->client = NULL;
 }
 
+/**
+* resolver: A service resolver object
+* iface: Numeric network interface index
+* proto: Protocol family specification
+* event: Type of callback event when resolving
+* name: the service name
+* type: The type of the service (must be HKP_SERVICE_TYPE)
+* domain: ignored
+* host_name: ignored
+* address: Protocol (address family) independent address structure. Address of the service
+* port: The port of the service
+* txt: ignored
+* flags: Some flags for lookup callback functions
+* data: ssd
+*
+* Adds services as sources to the SeahorseContext
+*
+**/
 static void 
 resolve_callback (AvahiServiceResolver *resolver, AvahiIfIndex iface, AvahiProtocol proto, 
                   AvahiResolverEvent event, const char *name, const char *type, const char *domain,
@@ -158,6 +189,20 @@ resolve_callback (AvahiServiceResolver *resolver, AvahiIfIndex iface, AvahiProto
     avahi_service_resolver_free (resolver);
 }
 
+/**
+* browser: The Avahi browser object
+* iface: Numeric network interface index
+* proto: Protocol family specification
+* event: Type of callback event when browsing
+* name: passed to avahi_service_resolver_new
+* type: passed to avahi_service_resolver_new
+* domain: passed to avahi_service_resolver_new
+* flags: Some flags for lookup callback functions
+* data: the ssd as user data
+*
+* Avahi callback. Called whenever a new service appears or is removed from the network.
+*
+**/
 static void 
 browse_callback(AvahiServiceBrowser *browser, AvahiIfIndex iface, AvahiProtocol proto,
                 AvahiBrowserEvent event, const char *name, const char *type, 
@@ -209,6 +254,14 @@ browse_callback(AvahiServiceBrowser *browser, AvahiIfIndex iface, AvahiProtocol
     }
 }
 
+/**
+* client: The AvahiClient
+* state: The state of this client
+* data: the ssd as user data
+*
+* Disconnects a failed Avahi client
+*
+**/
 static void 
 client_callback (AvahiClient *client, AvahiClientState state, void *data) 
 {
@@ -227,6 +280,14 @@ client_callback (AvahiClient *client, AvahiClientState state, void *data)
 
 #endif /* WITH_SHARING */
 
+/**
+* key: The key to prepend to the list
+* value: ignored
+* arg: a GSList of keys
+*
+* Prepend the key to the list arg
+*
+**/
 static void
 service_key_list (const gchar* key, const gchar* value, GSList **arg)
 {
@@ -239,6 +300,12 @@ service_key_list (const gchar* key, const gchar* value, GSList **arg)
  */
 
 
+/**
+* ssd: The SeahoreServiceDiscovery to init
+*
+* Connects Avahi (if available). Watches for HKP services.
+*
+**/
 static void
 seahorse_service_discovery_init (SeahorseServiceDiscovery *ssd)
 {
@@ -267,6 +334,12 @@ seahorse_service_discovery_init (SeahorseServiceDiscovery *ssd)
 #endif /* WITH_SHARING */
 }
 
+/**
+* gobject: The object to dispose
+*
+* Disposes the object, disconnects Avahi (if available)
+*
+**/
 static void
 seahorse_service_discovery_dispose (GObject *gobject)
 {
@@ -278,7 +351,13 @@ seahorse_service_discovery_dispose (GObject *gobject)
     G_OBJECT_CLASS (seahorse_service_discovery_parent_class)->dispose (gobject);
 }
 
-/* free private vars */
+
+/**
+* gobject: The object to finalize
+*
+* frees private vars
+*
+**/
 static void
 seahorse_service_discovery_finalize (GObject *gobject)
 {
@@ -299,6 +378,12 @@ seahorse_service_discovery_finalize (GObject *gobject)
     G_OBJECT_CLASS (seahorse_service_discovery_parent_class)->finalize (gobject);
 }
 
+/**
+* klass: The SeahorseServiceDiscoveryClass to init
+*
+* Adds the signals "added" and "removed"
+*
+**/
 static void
 seahorse_service_discovery_class_init (SeahorseServiceDiscoveryClass *klass)
 {
@@ -322,12 +407,27 @@ seahorse_service_discovery_class_init (SeahorseServiceDiscoveryClass *klass)
  * PUBLIC 
  */
 
+/**
+ * seahorse_service_discovery_new:
+ *
+ * Creates a new SeahorseServiceDiscovery object
+ *
+ * Returns: The new SeahorseServiceDiscovery object
+ */
 SeahorseServiceDiscovery*   
 seahorse_service_discovery_new ()
 {
     return g_object_new (SEAHORSE_TYPE_SERVICE_DISCOVERY, NULL);
 }
 
+/**
+ * seahorse_service_discovery_list:
+ * @ssd: Extract the services from here
+ *
+ * Creates a list containing all the services in @ssd
+ *
+ * Returns: A #GSList containing the services
+ */
 GSList*                     
 seahorse_service_discovery_list (SeahorseServiceDiscovery *ssd)
 {
@@ -339,6 +439,15 @@ seahorse_service_discovery_list (SeahorseServiceDiscovery *ssd)
     return *arg;
 }
 
+/**
+ * seahorse_service_discovery_get_uri:
+ * @ssd: The SeahorseServiceDiscovery to search in
+ * @service: the service to look up
+ *
+ * Finds the @service in @ssd and returns the URI stored there
+ *
+ * Returns: The URI stored in the services in @ssd
+ */
 const gchar*                
 seahorse_service_discovery_get_uri (SeahorseServiceDiscovery *ssd, const gchar *service)
 {
@@ -346,6 +455,15 @@ seahorse_service_discovery_get_uri (SeahorseServiceDiscovery *ssd, const gchar *
     return (const gchar*)g_hash_table_lookup (ssd->services, service);
 }
 
+/**
+ * seahorse_service_discovery_get_uris:
+ * @ssd: The SeahorseServiceDiscovery to search in
+ * @services: the services to look up
+ *
+ * Finds the @services in @ssd and returns the URIs stored there as a #GSList
+ *
+ * Returns: A #GSList of all found URIs
+ */
 GSList*
 seahorse_service_discovery_get_uris (SeahorseServiceDiscovery *ssd, GSList *services)
 {