Doxygen documentation cleanups:

* Hide a few irrelevant header files and definitions from doxygen to make the docs shorter
* Update some texts
* Put functions into categories


git-svn-id: file:///home/lennart/svn/public/avahi/trunk@1477 941a03a8-eaeb-0310-b9a0-b1bbd8fe43fe

3 files changed, 147 insertions, 95 deletions

diff --git a/avahi-client/client.h b/avahi-client/client.h
index 6a12e9a..2f86d02 100644
--- a/avahi-client/client.h
+++ b/avahi-client/client.h
@@ -58,6 +58,8 @@ typedef void (*AvahiClientCallback) (
     AvahiClientState state /**< The new state of the client */,
     void* userdata /**< The user data that was passed to avahi_client_new() */);
 
+/** @{ \name Construction and destruction */
+
 /** Creates a new client instance */
 AvahiClient* avahi_client_new (
     const AvahiPoll *poll_api /**< The abstract event loop API to use */,
@@ -71,6 +73,10 @@ AvahiClient* avahi_client_new (
  * to such objects become invalid! */
 void avahi_client_free(AvahiClient *client);
 
+/** @} */
+
+/** @{ \name Properties */
+
 /** Get the version of the server */
 const char* avahi_client_get_version_string (AvahiClient*);
 
@@ -89,15 +95,25 @@ const char* avahi_client_get_host_name_fqdn (AvahiClient*);
 /** Get state */
 AvahiClientState avahi_client_get_state(AvahiClient *client); 
 
-/** Get the last error number */
+/** @{ \name Error Handling */
+
+/** Get the last error number. See avahi_strerror() for converting this error code into a human readable string. */
 int avahi_client_errno (AvahiClient*);
 
+/** @} */
+
+/** \cond fulldocs */
 /** Return the local service cookie. returns AVAHI_SERVICE_COOKIE_INVALID on failure. */
 uint32_t avahi_client_get_local_service_cookie(AvahiClient *client);
+/** \endcond */
+
+/** @{ \name Libc NSS Support */
 
 /** Return 1 if gethostbyname() supports mDNS lookups, 0 otherwise. \since 0.6.5 */
 int avahi_nss_support(void);
 
+/** @} */
+
 AVAHI_C_DECL_END
 
 #endif
diff --git a/avahi-client/lookup.h b/avahi-client/lookup.h
index e7dec49..3e8210a 100644
--- a/avahi-client/lookup.h
+++ b/avahi-client/lookup.h
@@ -40,27 +40,11 @@
 
 AVAHI_C_DECL_BEGIN
 
+/** @{ \name Domain Browser */
+
 /** A domain browser object */
 typedef struct AvahiDomainBrowser AvahiDomainBrowser;
 
-/** A service browser object */
-typedef struct AvahiServiceBrowser AvahiServiceBrowser;
-
-/** A service type browser object */
-typedef struct AvahiServiceTypeBrowser AvahiServiceTypeBrowser;
-
-/** A service resolver object */
-typedef struct AvahiServiceResolver AvahiServiceResolver;
-
-/** A service resolver object */
-typedef struct AvahiHostNameResolver AvahiHostNameResolver;
-
-/** An address resolver object */
-typedef struct AvahiAddressResolver AvahiAddressResolver;
-
-/** A record browser object */
-typedef struct AvahiRecordBrowser AvahiRecordBrowser;
-
 /** The function prototype for the callback of an AvahiDomainBrowser */
 typedef void (*AvahiDomainBrowserCallback) (
     AvahiDomainBrowser *b,
@@ -71,98 +55,76 @@ typedef void (*AvahiDomainBrowserCallback) (
     AvahiLookupResultFlags flags,
     void *userdata);
 
-/** The function prototype for the callback of an AvahiServiceBrowser */
-typedef void (*AvahiServiceBrowserCallback) (
-    AvahiServiceBrowser *b,
+/** Browse for domains on the local network */
+AvahiDomainBrowser* avahi_domain_browser_new (
+    AvahiClient *client,
     AvahiIfIndex interface,
     AvahiProtocol protocol,
-    AvahiBrowserEvent event,
-    const char *name,
-    const char *type,
     const char *domain,
-    AvahiLookupResultFlags flags,
+    AvahiDomainBrowserType btype,
+    AvahiLookupFlags flags,
+    AvahiDomainBrowserCallback callback,
     void *userdata);
 
-/** The function prototype for the callback of an AvahiServiceTypeBrowser */
-typedef void (*AvahiServiceTypeBrowserCallback) (
-    AvahiServiceTypeBrowser *b,
+/** Get the parent client of an AvahiDomainBrowser object */
+AvahiClient* avahi_domain_browser_get_client (AvahiDomainBrowser *);
+
+/** Cleans up and frees an AvahiDomainBrowser object */
+int avahi_domain_browser_free (AvahiDomainBrowser *);
+
+/** @} */
+
+/** @{ \name Service Browser */
+
+/** A service browser object */
+typedef struct AvahiServiceBrowser AvahiServiceBrowser;
+
+/** The function prototype for the callback of an AvahiServiceBrowser */
+typedef void (*AvahiServiceBrowserCallback) (
+    AvahiServiceBrowser *b,
     AvahiIfIndex interface,
     AvahiProtocol protocol,
     AvahiBrowserEvent event,
+    const char *name,
     const char *type,
     const char *domain,
     AvahiLookupResultFlags flags,
     void *userdata);
 
-/** The function prototype for the callback of an AvahiServiceResolver */
-typedef void (*AvahiServiceResolverCallback) (
-    AvahiServiceResolver *r,
+/** Browse for services of a type on the local network */
+AvahiServiceBrowser* avahi_service_browser_new (
+    AvahiClient *client,
     AvahiIfIndex interface,
     AvahiProtocol protocol,
-    AvahiResolverEvent event,
-    const char *name,
     const char *type,
     const char *domain,
-    const char *host_name,
-    const AvahiAddress *a,
-    uint16_t port,
-    AvahiStringList *txt,
-    AvahiLookupResultFlags flags, 
+    AvahiLookupFlags flags,
+    AvahiServiceBrowserCallback callback,
     void *userdata);
 
-/** The function prototype for the callback of an AvahiHostNameResolver */
-typedef void (*AvahiHostNameResolverCallback) (
-    AvahiHostNameResolver *r,
-    AvahiIfIndex interface,
-    AvahiProtocol protocol,
-    AvahiResolverEvent event,
-    const char *name,
-    const AvahiAddress *a,
-    AvahiLookupResultFlags flags, 
-    void *userdata);
+/** Get the parent client of an AvahiServiceBrowser object */
+AvahiClient* avahi_service_browser_get_client (AvahiServiceBrowser *);
 
-/** The function prototype for the callback of an AvahiAddressResolver */
-typedef void (*AvahiAddressResolverCallback) (
-    AvahiAddressResolver *r,
-    AvahiIfIndex interface,
-    AvahiProtocol protocol,
-    AvahiResolverEvent event,
-    const AvahiAddress *a,
-    const char *name,
-    AvahiLookupResultFlags flags, 
-    void *userdata);
+/** Cleans up and frees an AvahiServiceBrowser object */
+int avahi_service_browser_free (AvahiServiceBrowser *);
 
-/** The function prototype for the callback of an AvahiRecordBrowser */
-typedef void (*AvahiRecordBrowserCallback) (
-    AvahiRecordBrowser *b,
-    AvahiIfIndex interface,
-    AvahiProtocol protocol,
-    AvahiBrowserEvent event,
-    const char *name,
-    uint16_t clazz,
-    uint16_t type,
-    const void *rdata,
-    size_t size,
-    AvahiLookupResultFlags flags,
-    void *userdata);
+/** @} */
 
-/** Browse for domains on the local network */
-AvahiDomainBrowser* avahi_domain_browser_new (
-    AvahiClient *client,
+/** \cond fulldocs */
+/** A service type browser object */
+typedef struct AvahiServiceTypeBrowser AvahiServiceTypeBrowser;
+
+/** The function prototype for the callback of an AvahiServiceTypeBrowser */
+typedef void (*AvahiServiceTypeBrowserCallback) (
+    AvahiServiceTypeBrowser *b,
     AvahiIfIndex interface,
     AvahiProtocol protocol,
+    AvahiBrowserEvent event,
+    const char *type,
     const char *domain,
-    AvahiDomainBrowserType btype,
-    AvahiLookupFlags flags,
-    AvahiDomainBrowserCallback callback,
+    AvahiLookupResultFlags flags,
     void *userdata);
 
-/** Get the parent client of an AvahiDomainBrowser object */
-AvahiClient* avahi_domain_browser_get_client (AvahiDomainBrowser *);
-
-/** Cleans up and frees an AvahiDomainBrowser object */
-int avahi_domain_browser_free (AvahiDomainBrowser *);
-
 /** Browse for service types on the local network */
 AvahiServiceTypeBrowser* avahi_service_type_browser_new (
     AvahiClient *client,
@@ -179,23 +141,29 @@ AvahiClient* avahi_service_type_browser_get_client (AvahiServiceTypeBrowser *);
 /** Cleans up and frees an AvahiServiceTypeBrowser object */
 int avahi_service_type_browser_free (AvahiServiceTypeBrowser *);
 
-/** Browse for services of a type on the local network */
-AvahiServiceBrowser* avahi_service_browser_new (
-    AvahiClient *client,
+/** \endcond */
+
+/** @{ \name Service Resolver */
+
+/** A service resolver object */
+typedef struct AvahiServiceResolver AvahiServiceResolver;
+
+/** The function prototype for the callback of an AvahiServiceResolver */
+typedef void (*AvahiServiceResolverCallback) (
+    AvahiServiceResolver *r,
     AvahiIfIndex interface,
     AvahiProtocol protocol,
+    AvahiResolverEvent event,
+    const char *name,
     const char *type,
     const char *domain,
-    AvahiLookupFlags flags,
-    AvahiServiceBrowserCallback callback,
+    const char *host_name,
+    const AvahiAddress *a,
+    uint16_t port,
+    AvahiStringList *txt,
+    AvahiLookupResultFlags flags, 
     void *userdata);
 
-/** Get the parent client of an AvahiServiceBrowser object */
-AvahiClient* avahi_service_browser_get_client (AvahiServiceBrowser *);
-
-/** Cleans up and frees an AvahiServiceBrowser object */
-int avahi_service_browser_free (AvahiServiceBrowser *);
-
 /** Create a new service resolver object. Please make sure to pass all
  * the service data you received via avahi_service_browser_new()'s
  * callback function, especially interface and protocol. */
@@ -217,6 +185,23 @@ AvahiClient* avahi_service_resolver_get_client (AvahiServiceResolver *);
 /** Free a service resolver object */
 int avahi_service_resolver_free(AvahiServiceResolver *r);
 
+/** @} */
+
+/** \cond fulldocs */
+/** A service resolver object */
+typedef struct AvahiHostNameResolver AvahiHostNameResolver;
+
+/** The function prototype for the callback of an AvahiHostNameResolver */
+typedef void (*AvahiHostNameResolverCallback) (
+    AvahiHostNameResolver *r,
+    AvahiIfIndex interface,
+    AvahiProtocol protocol,
+    AvahiResolverEvent event,
+    const char *name,
+    const AvahiAddress *a,
+    AvahiLookupResultFlags flags, 
+    void *userdata);
+
 /** Create a new hostname resolver object */
 AvahiHostNameResolver * avahi_host_name_resolver_new(
     AvahiClient *client,
@@ -234,6 +219,20 @@ AvahiClient* avahi_host_name_resolver_get_client (AvahiHostNameResolver *);
 /** Free a hostname resolver object */
 int avahi_host_name_resolver_free(AvahiHostNameResolver *r);
 
+/** An address resolver object */
+typedef struct AvahiAddressResolver AvahiAddressResolver;
+
+/** The function prototype for the callback of an AvahiAddressResolver */
+typedef void (*AvahiAddressResolverCallback) (
+    AvahiAddressResolver *r,
+    AvahiIfIndex interface,
+    AvahiProtocol protocol,
+    AvahiResolverEvent event,
+    const AvahiAddress *a,
+    const char *name,
+    AvahiLookupResultFlags flags, 
+    void *userdata);
+
 /** Create a new address resolver object from an AvahiAddress object */
 AvahiAddressResolver* avahi_address_resolver_new(
     AvahiClient *client,
@@ -250,6 +249,27 @@ AvahiClient* avahi_address_resolver_get_client (AvahiAddressResolver *);
 /** Free a AvahiAddressResolver resolver object */
 int avahi_address_resolver_free(AvahiAddressResolver *r);
 
+/** \endcond */
+
+/** @{ \name Record Browser */
+
+/** A record browser object */
+typedef struct AvahiRecordBrowser AvahiRecordBrowser;
+
+/** The function prototype for the callback of an AvahiRecordBrowser */
+typedef void (*AvahiRecordBrowserCallback) (
+    AvahiRecordBrowser *b,
+    AvahiIfIndex interface,
+    AvahiProtocol protocol,
+    AvahiBrowserEvent event,
+    const char *name,
+    uint16_t clazz,
+    uint16_t type,
+    const void *rdata,
+    size_t size,
+    AvahiLookupResultFlags flags,
+    void *userdata);
+
 /** Browse for records of a type on the local network */
 AvahiRecordBrowser* avahi_record_browser_new(
     AvahiClient *client,
@@ -268,6 +288,8 @@ AvahiClient* avahi_record_browser_get_client(AvahiRecordBrowser *);
 /** Cleans up and frees an AvahiRecordBrowser object */
 int avahi_record_browser_free(AvahiRecordBrowser *);
 
+/** @} */
+
 AVAHI_C_DECL_END
 
 #endif
diff --git a/avahi-client/publish.h b/avahi-client/publish.h
index 98f4f98..1e40b18 100644
--- a/avahi-client/publish.h
+++ b/avahi-client/publish.h
@@ -50,6 +50,8 @@ typedef void (*AvahiEntryGroupCallback) (
     AvahiEntryGroupState state /**< The new state of the entry group */,
     void* userdata /* The arbitrary user data pointer originally passed to avahi_entry_group_new()*/);
 
+/** @{ \name Construction and destruction */
+
 /** Create a new AvahiEntryGroup object */
 AvahiEntryGroup* avahi_entry_group_new(
     AvahiClient* c,
@@ -59,6 +61,10 @@ AvahiEntryGroup* avahi_entry_group_new(
 /** Clean up and free an AvahiEntryGroup object */
 int avahi_entry_group_free (AvahiEntryGroup *);
 
+/** @} */
+
+/** @{ \name State */
+
 /** Commit an AvahiEntryGroup. The entries in the entry group are now registered on the network. Commiting empty entry groups is considered an error. */
 int avahi_entry_group_commit (AvahiEntryGroup*);
 
@@ -74,6 +80,10 @@ int avahi_entry_group_is_empty (AvahiEntryGroup*);
 /** Get an AvahiEntryGroup's owning client instance */
 AvahiClient* avahi_entry_group_get_client (AvahiEntryGroup*);
 
+/** @} */
+
+/** @{ \name Adding and updating entries */
+
 /** Add a service. Takes a variable NULL terminated list of TXT record strings as last arguments. Please note that this service is not announced on the network before avahi_entry_group_commit() is called. */
 int avahi_entry_group_add_service(
     AvahiEntryGroup *group,
@@ -133,6 +143,7 @@ int avahi_entry_group_update_service_txt_strlst(
     const char *domain,   
     AvahiStringList *strlst);
 
+/** \cond fulldocs */
 /** Add a host/address pair */
 int avahi_entry_group_add_address(
     AvahiEntryGroup *group,
@@ -141,6 +152,7 @@ int avahi_entry_group_add_address(
     AvahiPublishFlags flags,
     const char *name /**< The FDQN of the new hostname to register */,
     const AvahiAddress *a /**< The address this host name shall map to */);
+/** \endcond */
 
 /** Add an arbitrary record. I hope you know what you do. */
 int avahi_entry_group_add_record(
@@ -155,6 +167,8 @@ int avahi_entry_group_add_record(
     const void *rdata,
     size_t size);
 
+/** @} */
+
 AVAHI_C_DECL_END
 
 #endif