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

10 files changed, 346 insertions, 149 deletions

diff --git a/Makefile.am b/Makefile.am
index 0411c74..2071916 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -76,16 +76,15 @@ SUBDIRS = \
 
 DX_INPUT = \
 	$(srcdir)/avahi-common/address.h \
+	$(srcdir)/avahi-common/malloc.h \
 	$(srcdir)/avahi-common/strlst.h \
 	$(srcdir)/avahi-common/alternative.h \
 	$(srcdir)/avahi-common/defs.h \
 	$(srcdir)/avahi-common/error.h \
-	$(srcdir)/avahi-common/malloc.h \
 	$(srcdir)/avahi-common/domain.h \
 	$(srcdir)/avahi-common/watch.h \
 	$(srcdir)/avahi-common/simple-watch.h \
-	$(srcdir)/avahi-common/thread-watch.h \
-	$(srcdir)/avahi-common/timeval.h
+	$(srcdir)/avahi-common/thread-watch.h
 
 DX_EXAMPLE_PATH = $(srcdir)/examples
 DX_EXAMPLE_PATTERNS = *.c
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
diff --git a/avahi-common/address.h b/avahi-common/address.h
index b8706ee..5c2f580 100644
--- a/avahi-common/address.h
+++ b/avahi-common/address.h
@@ -79,19 +79,31 @@ typedef struct AvahiAddress {
     } data;
 } AvahiAddress;
 
+/** @{ \name Comparison */
+
 /** Compare two addresses. Returns 0 when equal, a negative value when a < b, a positive value when a > b. */
 int avahi_address_cmp(const AvahiAddress *a, const AvahiAddress *b);
 
+/** @} */
+
+/** @{ \name String conversion */
+
 /** Convert the specified address *a to a human readable character string, use AVAHI_ADDRESS_STR_MAX to allocate an array of the right size */
 char *avahi_address_snprint(char *ret_s, size_t length, const AvahiAddress *a);
 
-/** Convert the specifeid human readable character string to an
+/** Convert the specified human readable character string to an
  * address structure. Set af to AVAHI_UNSPEC for automatic address
  * family detection. */
 AvahiAddress *avahi_address_parse(const char *s, AvahiProtocol af, AvahiAddress *ret_addr);
 
+/** @} */
+
+/** \cond fulldocs */
 /** Generate the DNS reverse lookup name for an IPv4 or IPv6 address. */
 char* avahi_reverse_lookup_name(const AvahiAddress *a, char *ret_s, size_t length);
+/** \endcond */
+
+/** @{ \name Protocol/address family handling */
 
 /** Map AVAHI_PROTO_xxx constants to Unix AF_xxx constants */
 int avahi_proto_to_af(AvahiProtocol proto);
@@ -102,6 +114,8 @@ AvahiProtocol avahi_af_to_proto(int af);
 /** Return a textual representation of the specified protocol number. i.e. "IPv4", "IPv6" or "UNSPEC" */
 const char* avahi_proto_to_string(AvahiProtocol proto);
 
+/** @} */
+
 AVAHI_C_DECL_END
 
 #endif
diff --git a/avahi-common/defs.h b/avahi-common/defs.h
index 4efa5ad..59bf271 100644
--- a/avahi-common/defs.h
+++ b/avahi-common/defs.h
@@ -31,7 +31,7 @@
  * \section choose_api Choosing an API
  *
  * Avahi provides three programming APIs for integration of
- * mDNS/DNS-SD features into your progams:
+ * mDNS/DNS-SD features into your C progams:
  *
  * \li <b>avahi-core</b>: an API for embedding a complete mDNS/DNS-SD stack
  * into your software. This is intended for developers of embedded
@@ -51,16 +51,41 @@
  * In addition to the three APIs described above Avahi supports two
  * compatibility libraries:
  *
- * \li avahi-compat-libdns_sd: the original Bonjour API as documented
+ * \li <b>avahi-compat-libdns_sd</b>: the original Bonjour API as documented
  * in the header file "dns_sd.h" by Apple Computer, Inc.
  *
- * \li avahi-compat-howl: the HOWL API as released with HOWL 0.9.8 by
+ * \li <b>avahi-compat-howl</b>: the HOWL API as released with HOWL 0.9.8 by
  * Porchdog Software.
  *
  * Please note that these compatibility layers are incomplete and
  * generally a waste of resources. We strongly encourage everyone to
  * use our native APIs for newly written programs and to port older
  * programs to avahi-client!
+ *
+ * The native APIs (avahi-client and avahi-core) can be integrated
+ * into external event loops. We provide adapters for the following
+ * event loop implementations:
+ *
+ * \li <b>avahi-glib</b>: The GLIB main loop as used by GTk+/GNOME
+ *
+ * \li <b>avahi-qt</b>: The Qt main loop as used by Qt/KDE
+ *
+ * Finally, we provide a high-level Gtk+ GUI dialog called
+ * <b>avahi-ui</b> for user-friendly browsing for services.
+ *
+ * The doxygen-generated API documentation covers avahi-client
+ * (including its auxiliary APIs), the event loop adapters and
+ * avahi-ui. For the other APIs please consult the original
+ * documentation (for the compatibility APIs) or the header files.
+ *
+ * Please note that the doxygen-generated API documentation of the
+ * native Avahi API is not complete. A few definitions that are part
+ * of the Avahi API have been removed from this documentation, either
+ * because they are only relevant in a very few low-level applications
+ * or because they are considered obsolete. Please consult the C header
+ * files for all definitions that are part of the Avahi API. Please
+ * note that these hidden definitions are considered part of the Avahi
+ * API and will stay available in the API in the future.
  * 
  * \section error_reporting Error Reporting
  *
@@ -99,8 +124,8 @@
  * whenever the server state changes.
  * - Only register your services when the server is in state
  * AVAHI_SERVER_RUNNING. If you register your services in other server
- * states they might not be accessible since the local host name is
- * not established.
+ * states they might not be accessible since the local host name might not necessarily
+ * be established.
  * - Remove your services when the server enters
  * AVAHI_SERVER_COLLISION or AVAHI_SERVER_REGISTERING state. Your
  * services may no be reachable anymore since the local host name is
@@ -108,7 +133,7 @@
  * established.
  * - When registering services, use the following algorithm:
  *   - Create a new entry group (i.e. avahi_entry_group_new())
- *   - Add your service(s)/additional host names (i.e. avahi_entry_group_add_service())
+ *   - Add your service(s)/additional RRs/subtypes (e.g. avahi_entry_group_add_service())
  *   - Commit the entry group (i.e. avahi_entry_group_commit())
  * - Subscribe to entry group state changes.
  * - If the entry group enters AVAHI_ENTRY_GROUP_COLLISION state the
@@ -133,17 +158,11 @@
  *
  * - For normal applications you need to call avahi_service_browser_new()
  * for the service type you want to browse for. Use
- * avahi_client_resolve_service() to acquire service data for a a service
+ * avahi_service_resolver_new() to acquire service data for a service
  * name.
  * - You can use avahi_domain_browser_new() to get a list of announced
  * browsing domains. Please note that not all domains whith services
  * on the LAN are mandatorily announced.
- * - Network monitor software may use avahi_service_type_browser_new()
- * to browse for the list of available service types on the LAN. This
- * API should NOT be used in normal software since it increases
- * traffic immensly. In addition not all DNS-SD implementations
- * announce their services in away that they can be found with
- * avahi_server_type_browser_new().
  * - There is no need to subscribe to server state changes.
  *
  * \section daemon_dies How to Write a Client That Can Deal with Daemon Restarts
@@ -194,6 +213,17 @@
 
 AVAHI_C_DECL_BEGIN
 
+/** @{ \name States */
+
+/** States of a server object */
+typedef enum {
+    AVAHI_SERVER_INVALID,          /**< Invalid state (initial) */ 
+    AVAHI_SERVER_REGISTERING,      /**< Host RRs are being registered */
+    AVAHI_SERVER_RUNNING,          /**< All host RRs have been established */
+    AVAHI_SERVER_COLLISION,        /**< There is a collision with a host RR. All host RRs have been withdrawn, the user should set a new host name via avahi_server_set_host_name() */
+    AVAHI_SERVER_FAILURE           /**< Some fatal failure happened, the server is unable to proceed */
+} AvahiServerState;
+
 /** States of an entry group object */
 typedef enum {
     AVAHI_ENTRY_GROUP_UNCOMMITED,    /**< The group has not yet been commited, the user must still call avahi_entry_group_commit() */
@@ -203,15 +233,9 @@ typedef enum {
     AVAHI_ENTRY_GROUP_FAILURE        /**< Some kind of failure happened, the entries have been withdrawn */
 } AvahiEntryGroupState;
 
-/** The type of domain to browse for */
-typedef enum {
-    AVAHI_DOMAIN_BROWSER_BROWSE,            /**< Browse for a list of available browsing domains */
-    AVAHI_DOMAIN_BROWSER_BROWSE_DEFAULT,    /**< Browse for the default browsing domain */
-    AVAHI_DOMAIN_BROWSER_REGISTER,          /**< Browse for a list of available registering domains */
-    AVAHI_DOMAIN_BROWSER_REGISTER_DEFAULT,  /**< Browse for the default registering domain */
-    AVAHI_DOMAIN_BROWSER_BROWSE_LEGACY,     /**< Legacy browse domain - see DNS-SD spec for more information */
-    AVAHI_DOMAIN_BROWSER_MAX
-} AvahiDomainBrowserType;
+/** @} */
+
+/** @{ \name Flags */
 
 /** Some flags for publishing functions */
 typedef enum {
@@ -219,17 +243,23 @@ typedef enum {
     AVAHI_PUBLISH_NO_PROBE = 2,         /**< For raw records: Though the RRset is intended to be unique no probes shall be sent */
     AVAHI_PUBLISH_NO_ANNOUNCE = 4,      /**< For raw records: Do not announce this RR to other hosts */
     AVAHI_PUBLISH_ALLOW_MULTIPLE = 8,   /**< For raw records: Allow multiple local records of this type, even if they are intended to be unique */
+/** \cond fulldocs */
     AVAHI_PUBLISH_NO_REVERSE = 16,      /**< For address records: don't create a reverse (PTR) entry */
     AVAHI_PUBLISH_NO_COOKIE = 32,       /**< For service records: do not implicitly add the local service cookie to TXT data */
+/** \endcond */
     AVAHI_PUBLISH_UPDATE = 64,          /**< Update existing records instead of adding new ones */
+/** \cond fulldocs */
     AVAHI_PUBLISH_USE_WIDE_AREA = 128,  /**< Register the record using wide area DNS (i.e. unicast DNS update) */
     AVAHI_PUBLISH_USE_MULTICAST = 256   /**< Register the record using multicast DNS */
+/** \endcond */
 } AvahiPublishFlags;
 
 /** Some flags for lookup functions */
 typedef enum {
+/** \cond fulldocs */
     AVAHI_LOOKUP_USE_WIDE_AREA = 1,    /**< Force lookup via wide area DNS */
     AVAHI_LOOKUP_USE_MULTICAST = 2,    /**< Force lookup via multicast DNS */
+/** \endcond */
     AVAHI_LOOKUP_NO_TXT = 4,           /**< When doing service resolving, don't lookup TXT record */
     AVAHI_LOOKUP_NO_ADDRESS = 8        /**< When doing service resolving, don't lookup A/AAAA record */
 } AvahiLookupFlags;
@@ -244,6 +274,10 @@ typedef enum {
     AVAHI_LOOKUP_RESULT_STATIC = 32         /**< The returned data has been defined statically by some configuration option */
 } AvahiLookupResultFlags;
 
+/** @} */
+
+/** @{ \name Events */
+
 /** Type of callback event when browsing */
 typedef enum {
     AVAHI_BROWSER_NEW,               /**< The object is new on the network */
@@ -259,15 +293,23 @@ typedef enum {
     AVAHI_RESOLVER_FAILURE         /**< Resolving failed due to some reason which can be retrieved using avahi_server_errno()/avahi_client_errno() */
 } AvahiResolverEvent;
 
-/** States of a server object */
+/** @} */
+
+/** @{ \name Other definitions */
+
+/** The type of domain to browse for */
 typedef enum {
-    AVAHI_SERVER_INVALID,          /**< Invalid state (initial) */ 
-    AVAHI_SERVER_REGISTERING,      /**< Host RRs are being registered */
-    AVAHI_SERVER_RUNNING,          /**< All host RRs have been established */
-    AVAHI_SERVER_COLLISION,        /**< There is a collision with a host RR. All host RRs have been withdrawn, the user should set a new host name via avahi_server_set_host_name() */
-    AVAHI_SERVER_FAILURE           /**< Some fatal failure happened, the server is unable to proceed */
-} AvahiServerState;
+    AVAHI_DOMAIN_BROWSER_BROWSE,            /**< Browse for a list of available browsing domains */
+    AVAHI_DOMAIN_BROWSER_BROWSE_DEFAULT,    /**< Browse for the default browsing domain */
+    AVAHI_DOMAIN_BROWSER_REGISTER,          /**< Browse for a list of available registering domains */
+    AVAHI_DOMAIN_BROWSER_REGISTER_DEFAULT,  /**< Browse for the default registering domain */
+    AVAHI_DOMAIN_BROWSER_BROWSE_LEGACY,     /**< Legacy browse domain - see DNS-SD spec for more information */
+    AVAHI_DOMAIN_BROWSER_MAX
+} AvahiDomainBrowserType;
 
+/** @} */
+
+/** \cond fulldocs */
 /** For every service a special TXT item is implicitly added, which
  * contains a random cookie which is private to the local daemon. This
  * can be used by clients to determine if two services on two
@@ -276,6 +318,9 @@ typedef enum {
 
 /** In invalid cookie as special value */
 #define AVAHI_SERVICE_COOKIE_INVALID (0)
+/** \endcond fulldocs */
+
+/** @{ \name DNS RR definitions */
 
 /** DNS record types, see RFC 1035 */
 enum {
@@ -296,6 +341,8 @@ enum {
     AVAHI_DNS_CLASS_IN = 0x01,          /**< Probably the only class we will ever use */
 };
 
+/** @} */
+
 /** The default TTL for RRs which contain a host name of some kind. */
 #define AVAHI_DEFAULT_TTL_HOST_NAME (120)
 
diff --git a/avahi-common/domain.h b/avahi-common/domain.h
index 7073e1c..14d069d 100644
--- a/avahi-common/domain.h
+++ b/avahi-common/domain.h
@@ -45,6 +45,8 @@ AVAHI_C_DECL_BEGIN
 /** Maximum size of an unescaped label */
 #define AVAHI_LABEL_MAX 64
 
+/** @{ \name Normalization */
+
 /** Normalize a domain name into canonical form. This drops trailing
  * dots and removes useless backslash escapes. */
 char *avahi_normalize_name(const char *s, char *ret_s, size_t size);
@@ -54,9 +56,20 @@ char *avahi_normalize_name(const char *s, char *ret_s, size_t size);
  * result! */
 char *avahi_normalize_name_strdup(const char *s);
 
+/** @} */
+
+/** @{ \name Comparison */
+
 /** Return 1 when the specified domain names are equal, 0 otherwise */
 int avahi_domain_equal(const char *a, const char *b);
 
+/** Return some kind of hash value for the domain, useful for using domains as hash table keys. */
+unsigned avahi_domain_hash(const char *name);
+
+/** @} */
+
+/** @{ \name Escaping */
+
 /** Read the first label from the textual domain name *name, unescape
  * it and write it to dest, *name is changed to point to the next label*/
 char *avahi_unescape_label(const char **name, char *dest, size_t size);
@@ -64,26 +77,28 @@ char *avahi_unescape_label(const char **name, char *dest, size_t size);
 /** Escape the domain name in *src and write it to *ret_name */
 char *avahi_escape_label(const char* src, size_t src_length, char **ret_name, size_t *ret_size);
 
-/** Return a pointer to the type section of a subtype i.e. _foo._sub._bar._tcp => _bar._tcp */
-const char *avahi_get_type_from_subtype(const char *t);
+/** @} */
 
-/** Return 1 when the specified string contains a valid generic
+/** @{ \name Validity Checks */
+
+/** Return 1 when the specified string contains a valid generic DNS-SD
  * service type (i.e. a series of words starting with "_"), 0
  * otherwise */
 int avahi_is_valid_service_type_generic(const char *t);
 
-/** Return 1 when the specified string contains a valid strict service
- * type (i.e. consisting of only two words, the latter being either
- * _udp or _tcp), 0 otherwise */
+/** Return 1 when the specified string contains a valid strict DNS-SD
+ * service type (i.e. consisting of only two words, the latter being
+ * either _udp or _tcp), 0 otherwise */
 int avahi_is_valid_service_type_strict(const char *t);
 
-/** Return 1 when the specified string contains a valid service subtype, 0 otherwise */
+/** Return 1 when the specified string contains a valid DNS-SD service
+ * subtype, 0 otherwise */
 int avahi_is_valid_service_subtype(const char *t);
 
 /** Return 1 when the specified string contains a valid domain name, 0 otherwise */
 int avahi_is_valid_domain_name(const char *t);
 
-/** Return 1 when the specified string contains a valid service name, 0 otherwise */
+/** Return 1 when the specified string contains a valid DNS-SD service name, 0 otherwise */
 int avahi_is_valid_service_name(const char *t);
 
 /** Return 1 when the specified string contains a valid non-FQDN host name (i.e. without dots), 0 otherwise */
@@ -92,15 +107,25 @@ int avahi_is_valid_host_name(const char *t);
 /** Return 1 when the specified string contains a valid FQDN host name (i.e. with more than one label and non-numerical), 0 otherwise. \since 0.6.9 */
 int avahi_is_valid_fqdn(const char *t);
 
-/** Return some kind of hash value for the domain, useful for using domains as hash table keys. */
-unsigned avahi_domain_hash(const char *name);
+/** @} */
 
-/** Construct a valid complete service name from a name, a type and a domain */
+/** @{ \name DNS-SD service name handling */
+
+/** Construct a valid complete DNS-SD service name from a name, a type and a domain */
 int avahi_service_name_join(char *p, size_t size, const char *name, const char *type, const char *domain);
 
 /** Split a full service name into name, type and domain */
 int avahi_service_name_split(const char *p, char *name, size_t name_size, char *type, size_t type_size, char *domain, size_t domain_size);
 
+/** @} */
+
+/** @{ \name DNS-SD Subtype handling */
+
+/** Return a pointer to the type section of a subtype i.e. _foo._sub._bar._tcp => _bar._tcp */
+const char *avahi_get_type_from_subtype(const char *t);
+
+/** @} */
+
 AVAHI_C_DECL_END
 
 #endif
diff --git a/avahi-common/malloc.h b/avahi-common/malloc.h
index 40b6272..2430199 100644
--- a/avahi-common/malloc.h
+++ b/avahi-common/malloc.h
@@ -88,8 +88,10 @@ void avahi_set_allocator(const AvahiAllocator *a);
 /** Like sprintf() but store the result in a freshly allocated buffer. Free this with avahi_free() */
 char *avahi_strdup_printf(const char *fmt, ... ) AVAHI_GCC_PRINTF_ATTR12;
 
+/** \cond fulldocs */
 /** Same as avahi_strdup_printf() but take a va_list instead of varargs */
 char *avahi_strdup_vprintf(const char *fmt, va_list ap);
+/** \endcond */
 
 AVAHI_C_DECL_END
 
diff --git a/avahi-common/strlst.h b/avahi-common/strlst.h
index 26708a5..119e416 100644
--- a/avahi-common/strlst.h
+++ b/avahi-common/strlst.h
@@ -45,13 +45,17 @@ typedef struct AvahiStringList {
     uint8_t text[1]; /**< Character data */
 } AvahiStringList;
 
+/** @{ \name Construction and destruction */
+
 /** Create a new string list by taking a variable list of NUL
  * terminated strings. The strings are copied using g_strdup(). The
  * argument list must be terminated by a NULL pointer. */
 AvahiStringList *avahi_string_list_new(const char *txt, ...) AVAHI_GCC_SENTINEL;
 
+/** \cond fulldocs */
 /** Same as avahi_string_list_new() but pass a va_list structure */
 AvahiStringList *avahi_string_list_new_va(va_list va);
+/** \endcond */
 
 /** Create a new string list from a string array. The strings are
  * copied using g_strdup(). length should contain the length of the
@@ -61,6 +65,10 @@ AvahiStringList *avahi_string_list_new_from_array(const char **array, int length
 /** Free a string list */
 void avahi_string_list_free(AvahiStringList *l);
 
+/** @} */
+
+/** @{ \name Adding strings */
+
 /** Append a NUL terminated string to the specified string list. The
  * passed string is copied using g_strdup(). Returns the new list
  * start. */
@@ -69,8 +77,10 @@ AvahiStringList *avahi_string_list_add(AvahiStringList *l, const char *text);
 /** Append a new NUL terminated formatted string to the specified string list */
 AvahiStringList *avahi_string_list_add_printf(AvahiStringList *l, const char *format, ...) AVAHI_GCC_PRINTF_ATTR23;
 
+/** \cond fulldocs */
 /** Append a new NUL terminated formatted string to the specified string list */
 AvahiStringList *avahi_string_list_add_vprintf(AvahiStringList *l, const char *format, va_list va);
+/** \endcond */
 
 /** Append an arbitrary length byte string to the list. Returns the
  * new list start. */
@@ -88,21 +98,29 @@ AvahiStringList*avahi_string_list_add_anonymous(AvahiStringList *l, size_t size)
  * NULL pointer. Returns the new list start. */
 AvahiStringList *avahi_string_list_add_many(AvahiStringList *r, ...) AVAHI_GCC_SENTINEL;
 
+/** \cond fulldocs */
 /** Same as avahi_string_list_add_many(), but use a va_list
  * structure. Returns the new list start. */
 AvahiStringList *avahi_string_list_add_many_va(AvahiStringList *r, va_list va);
+/** \endcond */
+
+/** @} */
+
+/** @{ \name String list operations */
 
 /** Convert the string list object to a single character string,
  * seperated by spaces and enclosed in "". avahi_free() the result! This
  * function doesn't work well with string that contain NUL bytes. */
 char* avahi_string_list_to_string(AvahiStringList *l);
 
+/** \cond fulldocs */
 /** Serialize the string list object in a way that is compatible with
  * the storing of DNS TXT records. Strings longer than 255 bytes are truncated. */
 size_t avahi_string_list_serialize(AvahiStringList *l, void * data, size_t size);
 
 /** Inverse of avahi_string_list_serialize() */
 int avahi_string_list_parse(const void *data, size_t size, AvahiStringList **ret);
+/** \endcond */
 
 /** Compare to string lists */
 int avahi_string_list_equal(const AvahiStringList *a, const AvahiStringList *b);
@@ -116,6 +134,23 @@ AvahiStringList* avahi_string_list_reverse(AvahiStringList *l);
 /** Return the number of elements in the string list */
 unsigned avahi_string_list_length(const AvahiStringList *l);
 
+/** @} */
+
+/** @{ \name Accessing items */
+
+/** Returns the next item in the string list */
+AvahiStringList *avahi_string_list_get_next(AvahiStringList *l);
+
+/** Returns the text for the current item */
+uint8_t *avahi_string_list_get_text(AvahiStringList *l);
+
+/** Returns the size of the current text */
+size_t avahi_string_list_get_size(AvahiStringList *l);
+
+/** @} */
+
+/** @{ \name DNS-SD TXT pair handling */
+
 /** Find the string list entry for the given DNS-SD TXT key */
 AvahiStringList *avahi_string_list_find(AvahiStringList *l, const char *key);
 
@@ -133,18 +168,13 @@ AvahiStringList *avahi_string_list_add_pair(AvahiStringList *l, const char *key,
 /** Same as avahi_string_list_add_pair() but allow strings containing NUL bytes in *value. */
 AvahiStringList *avahi_string_list_add_pair_arbitrary(AvahiStringList *l, const char *key, const uint8_t *value, size_t size);
 
-/** Returns the next item in the string list */
-AvahiStringList *avahi_string_list_get_next(AvahiStringList *l);
-
-/** Returns the text for the current item */
-uint8_t *avahi_string_list_get_text(AvahiStringList *l);
-
-/** Returns the size of the current text */
-size_t avahi_string_list_get_size(AvahiStringList *l);
+/** @} */
 
+/** \cond fulldocs */
 /** Try to find a magic service cookie in the specified DNS-SD string
  * list. Or return AVAHI_SERVICE_COOKIE_INVALID if none is found. */
 uint32_t avahi_string_list_get_service_cookie(AvahiStringList *l);
+/** \endcond */
 
 AVAHI_C_DECL_END
 
diff --git a/avahi-ui/avahi-ui.h b/avahi-ui/avahi-ui.h
index 592d09b..b314957 100644
--- a/avahi-ui/avahi-ui.h
+++ b/avahi-ui/avahi-ui.h
@@ -66,6 +66,8 @@ GType aui_service_dialog_get_type(void) G_GNUC_CONST;
 /** The GTK service dialog structure */
 typedef struct _AuiServiceDialog AuiServiceDialog;
 
+/** @{ \name Construction */
+
 /** Create a new service browser dialog with the specific title,
  * parent window and the speicified buttons. The buttons are specified
  * in a similar way to GtkFileChooserDialog. Please note that at least
@@ -75,13 +77,17 @@ GtkWidget* aui_service_dialog_new(
         GtkWindow *parent,
         const gchar *first_button_text, ...) G_GNUC_NULL_TERMINATED;
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
+/** \cond fulldocs */
 GtkWidget *aui_service_dialog_new_valist(
         gchar *title,
         GtkWindow *parent,
         const gchar *first_button_text,
         va_list varargs);
-#endif
+/** \endcond }
+
+/** @} */
+
+/** @{ \name Service types to browse for */
 
 /** Select the service types to browse for. Takes a NULL terminated list of DNS-SD service types. i.e. _http._tcp */
 void aui_service_dialog_set_browse_service_types(AuiServiceDialog *d, const gchar *type, ...) G_GNUC_NULL_TERMINATED;
@@ -90,11 +96,19 @@ void aui_service_dialog_set_browse_service_typesv(AuiServiceDialog *d, const gch
 /** Return the service types currently browsed for. i.e. what was previously set with aui_service_dialog_set_browse_service_types() */
 const gchar*const* aui_service_dialog_get_browse_service_types(AuiServiceDialog *d);
 
+/** @} */
+
+/** @{ \name Domain to browse in */
+
 /** Set the domain to browse in */
 void aui_service_dialog_set_domain(AuiServiceDialog *d, const gchar *domain);
 /** Query the domain that is browsed in */
 const gchar* aui_service_dialog_get_domain(AuiServiceDialog *d);
 
+/** @} */
+
+/** @{ \name Selected service item */
+
 /** Set the service type for the service to select */
 void aui_service_dialog_set_service_type(AuiServiceDialog *d, const gchar *name);
 
@@ -107,6 +121,10 @@ void aui_service_dialog_set_service_name(AuiServiceDialog *d, const gchar *name)
 /** Query the service name of the currently select service */
 const gchar* aui_service_dialog_get_service_name(AuiServiceDialog *d);
 
+/** @} */
+
+/** @{ \name Resolved service information */
+
 /** Return the IP address of the selected service. (Only valid if host name resolving has not been disabled via aui_service_dialog_set_resolve_host_name()) */
 const AvahiAddress* aui_service_dialog_get_address(AuiServiceDialog *d);
 
@@ -119,6 +137,10 @@ const gchar* aui_service_dialog_get_host_name(AuiServiceDialog *d);
 /** Return the TXT metadata of the selected service */
 const AvahiStringList *aui_service_dialog_get_txt_data(AuiServiceDialog *d);
 
+/** @} */
+
+/** @{ \name Resolving settings */
+
 /** Disable/Enable automatic service resolving. Disabling this feature
  * will require you to resolve the selected service on our own. I.e. the port
  * number, the TXT data and the host name/IP address will not be
@@ -141,6 +163,10 @@ void aui_service_dialog_set_resolve_host_name(AuiServiceDialog *d, gboolean reso
 /** Query the last status of aui_service_dialog_set_resolve_host_name() */
 gboolean aui_service_dialog_get_resolve_host_name(AuiServiceDialog *d);
 
+/** @} */
+
+/** @{ \name Address family */
+
 /** Select the address family to look for services of. This can be
 used to look only for IPv6 services or only for IPv4 services. By
 default avahi-ui will browse for both IPv4 and IPv6 services.*/
@@ -149,6 +175,8 @@ void aui_service_dialog_set_address_family(AuiServiceDialog *d, AvahiProtocol pr
 /** Query the address family we're looking for. */
 AvahiProtocol aui_service_dialog_get_address_family(AuiServiceDialog *d);
 
+/** @} */
+
 G_END_DECLS
 
 #endif