* remove lots of DOXYGEN_SHOULD_SKIP_THIS from the header files, use doxygen macro expansion instead

* split of exotic functions from avahi-core/rr.h to avahi-core/rr-util.h
* update doxygen docs


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

15 files changed, 25 insertions, 61 deletions

diff --git a/avahi-common/address.h b/avahi-common/address.h
index 95eb392..53f8d06 100644
--- a/avahi-common/address.h
+++ b/avahi-common/address.h
@@ -29,9 +29,7 @@
 
 #include <avahi-common/cdecl.h>
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
-#endif
 
 /** Protocol family specification, takes the values AVAHI_PROTO_INET, AVAHI_PROTO_INET6, AVAHI_PROTO_UNSPEC */
 typedef int AvahiProtocol;
@@ -61,17 +59,17 @@ enum {
 #define AVAHI_PROTO_VALID(protocol) (((protocol) == AVAHI_PROTO_INET) || ((protocol) == AVAHI_PROTO_INET6) || ((protocol) == AVAHI_PROTO_UNSPEC))
 
 /** An IPv4 address */
-typedef struct {
+typedef struct AvahiIPv4Address {
     uint32_t address; /**< Address data in network byte order. */
 } AvahiIPv4Address;
 
 /** An IPv6 address */
-typedef struct {
+typedef struct AvahiIPv6Address {
     uint8_t address[16]; /**< Address data */
 } AvahiIPv6Address;
 
 /** Protocol (address family) independent address structure */
-typedef struct {
+typedef struct AvahiAddress {
     AvahiProtocol proto; /**< Address family */
 
     union {
@@ -104,8 +102,6 @@ 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);
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
-#endif
 
 #endif
diff --git a/avahi-common/alternative.h b/avahi-common/alternative.h
index fa45d96..4f0e58b 100644
--- a/avahi-common/alternative.h
+++ b/avahi-common/alternative.h
@@ -26,9 +26,7 @@
 
 #include <avahi-common/cdecl.h>
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
-#endif
 
 /** Find an alternative for the specified host name. If called with an
  * original host name, "2" is appended, Afterwards the number is
@@ -42,8 +40,6 @@ char *avahi_alternative_host_name(const char *s);
     "foo #3" and so on.) avahi_free() the result. */
 char *avahi_alternative_service_name(const char *s);
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
-#endif
 
 #endif
diff --git a/avahi-common/cdecl.h b/avahi-common/cdecl.h
index ca462c8..b08e2a0 100644
--- a/avahi-common/cdecl.h
+++ b/avahi-common/cdecl.h
@@ -23,7 +23,6 @@
 ***/
 
 /** \file cdecl.h C++ compatibility */
-
 #ifdef __cplusplus
 /** If using C++ this macro enables C mode, otherwise does nothing */
 #define AVAHI_C_DECL_BEGIN extern "C" {
diff --git a/avahi-common/dbus-watch-glue.h b/avahi-common/dbus-watch-glue.h
index e815b45..101fa3f 100644
--- a/avahi-common/dbus-watch-glue.h
+++ b/avahi-common/dbus-watch-glue.h
@@ -26,6 +26,10 @@
 
 #include <avahi-common/watch.h>
 
+AVAHI_C_DECL_BEGIN
+
 int avahi_dbus_connection_glue(DBusConnection *c, const AvahiPoll *poll_api);
 
+AVAHI_C_DECL_END
+
 #endif
diff --git a/avahi-common/dbus.h b/avahi-common/dbus.h
index 9cafbde..56f9d91 100644
--- a/avahi-common/dbus.h
+++ b/avahi-common/dbus.h
@@ -27,9 +27,7 @@
 #include <avahi-common/cdecl.h>
 #include <dbus/dbus.h>
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
-#endif
 
 #define AVAHI_DBUS_NAME "org.freedesktop.Avahi"
 #define AVAHI_DBUS_INTERFACE_SERVER AVAHI_DBUS_NAME".Server"
@@ -95,8 +93,6 @@ int avahi_error_dbus_to_number(const char *s);
 /** Convert an Avahi error number into a DBus error string.  Result should not be freed */
 const char * avahi_error_number_to_dbus(int error);
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
-#endif
 
 #endif
diff --git a/avahi-common/defs.h b/avahi-common/defs.h
index 2dcc829..14a0ba3 100644
--- a/avahi-common/defs.h
+++ b/avahi-common/defs.h
@@ -48,6 +48,20 @@
  * 
  * All three APIs are very similar, however avahi-core is the most powerful.
  *
+ * In addition to the three APIs described above Avahi supports two
+ * compatibility libraries:
+ *
+ * \li avahi-compat-libdns_sd: 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
+ * 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 one of them!
+ * 
  * \section error_reporting Error Reporting
  *
  * Some notes on the Avahi error handling:
@@ -104,8 +118,7 @@
  * avahi_alternative_service_name()) and commit again. Please do not
  * free the entry group and create a new one. This would inhibit some
  * traffic limiting algorithms in mDNS.
- * - When you need to modify your services, reset the entry group
- * (i.e. avahi_entry_group_reset()) and add them back. Please do not
+ * - When you need to modify your services, use the AVAHI_PUBLISH_UPDATE flag. Please do not
  * free the entry group and create a new one. This would inhibit some
  * traffic limiting algorithms in mDNS.
  *
@@ -117,7 +130,7 @@
  * for the service type you want to browse for. Use
  * avahi_client_resolve_service() to acquire service data for a a service
  * name.
- * - You can use avahi_domain_browser() to get a list of announced
+ * - 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()
@@ -130,9 +143,7 @@
  *  
  */
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
-#endif
 
 /** States of an entry group object */
 typedef enum {
@@ -214,8 +225,6 @@ typedef enum {
 /** In invalid cookie as special value */
 #define AVAHI_SERVICE_COOKIE_INVALID (0)
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
-#endif
 
 #endif
diff --git a/avahi-common/domain.h b/avahi-common/domain.h
index e5869ce..53897e7 100644
--- a/avahi-common/domain.h
+++ b/avahi-common/domain.h
@@ -29,9 +29,7 @@
 
 #include <avahi-common/cdecl.h>
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
-#endif
 
 /** The maximum length of a a fully escaped domain name C string. This
  * is calculated like this: RFC1034 mandates maximum length of FQDNs
@@ -100,8 +98,6 @@ int avahi_service_name_join(char *p, size_t size, const char *name, const char *
 /** 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);
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
-#endif
 
 #endif
diff --git a/avahi-common/error.h b/avahi-common/error.h
index 270aece..a7c97a7 100644
--- a/avahi-common/error.h
+++ b/avahi-common/error.h
@@ -26,9 +26,7 @@
 
 #include <avahi-common/cdecl.h>
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
-#endif
 
 /** Error codes used by avahi */
 enum { 
@@ -97,8 +95,6 @@ enum {
 /** Return a human readable error string for the specified error code */
 const char *avahi_strerror(int error);
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
-#endif
 
 #endif
diff --git a/avahi-common/gccmacro.h b/avahi-common/gccmacro.h
index 33ff847..c32a29d 100644
--- a/avahi-common/gccmacro.h
+++ b/avahi-common/gccmacro.h
@@ -26,9 +26,7 @@
 
 #include <avahi-common/cdecl.h>
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
-#endif
 
 #ifdef __GNUC__
 #if __GNUC__ >= 4
@@ -61,8 +59,6 @@ AVAHI_C_DECL_BEGIN
 #define AVAHI_GCC_NORETURN
 #endif
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
-#endif
 
 #endif
diff --git a/avahi-common/llist.h b/avahi-common/llist.h
index 25daf2b..37474e1 100644
--- a/avahi-common/llist.h
+++ b/avahi-common/llist.h
@@ -28,9 +28,7 @@
 
 #include <avahi-common/cdecl.h>
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
-#endif
 
 /** The head of the linked list. Use this in the structure that shall
  * contain the head of the linked list */
@@ -74,9 +72,6 @@ AVAHI_C_DECL_BEGIN
                                     _item->name##_next = _item->name##_prev = NULL; \
                                     } while(0)
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
-#endif
-
 
 #endif
diff --git a/avahi-common/malloc.h b/avahi-common/malloc.h
index d0e620a..d911a3a 100644
--- a/avahi-common/malloc.h
+++ b/avahi-common/malloc.h
@@ -60,15 +60,12 @@ char *avahi_strndup(const char *s, size_t l);
 void *avahi_memdup(const void *s, size_t l);
 
 /** Wraps allocator functions */
-typedef struct AvahiAllocator AvahiAllocator;
-
-/** Wraps allocator functions */
-struct AvahiAllocator {
+typedef struct AvahiAllocator {
     void* (*malloc)(size_t size);     
     void (*free)(void *p);           
     void* (*realloc)(void *p, size_t size);
     void* (*calloc)(size_t nmemb, size_t size);   /**< May be NULL */
-};
+} AvahiAllocator;
 
 /** Change the allocator. May be NULL to return to default (libc)
  * allocators. The structure is not copied! */
diff --git a/avahi-common/rlist.h b/avahi-common/rlist.h
index 57b258c..0b88955 100644
--- a/avahi-common/rlist.h
+++ b/avahi-common/rlist.h
@@ -26,9 +26,7 @@
 
 #include "llist.h"
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
-#endif
 
 /** A doubly linked list type */
 typedef struct AvahiRList AvahiRList;
@@ -48,8 +46,6 @@ AvahiRList* avahi_rlist_remove(AvahiRList *r, void *data);
 /** Remove the specified item from the list and return the new beginning */
 AvahiRList* avahi_rlist_remove_by_link(AvahiRList *r, AvahiRList *n);
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
-#endif
 
 #endif
diff --git a/avahi-common/simple-watch.h b/avahi-common/simple-watch.h
index 5a4b37d..7c83db3 100644
--- a/avahi-common/simple-watch.h
+++ b/avahi-common/simple-watch.h
@@ -28,9 +28,7 @@
 #include <avahi-common/cdecl.h>
 #include <avahi-common/watch.h>
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
-#endif
 
 /** A main loop object. Main loops of this type aren't very flexible
  * since they only support a single wakeup type. Nevertheless it
@@ -84,8 +82,6 @@ int avahi_simple_poll_loop(AvahiSimplePoll *s);
 /** Wakeup the main loop. (for threaded environments) */
 void avahi_simple_poll_wakeup(AvahiSimplePoll *s);
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
-#endif
 
 #endif
diff --git a/avahi-common/timeval.h b/avahi-common/timeval.h
index d925719..8bdb073 100644
--- a/avahi-common/timeval.h
+++ b/avahi-common/timeval.h
@@ -29,9 +29,7 @@
 
 #include <avahi-common/cdecl.h>
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
-#endif
 
 /** A numeric data type for storing microsecond values. (signed 64bit integer) */
 typedef int64_t AvahiUsec;
@@ -53,8 +51,6 @@ AvahiUsec avahi_age(const struct timeval *a);
  * the jitter */
 struct timeval *avahi_elapse_time(struct timeval *tv, unsigned ms, unsigned j);
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
-#endif
 
 #endif
diff --git a/avahi-common/watch.h b/avahi-common/watch.h
index b973683..bc8ae2f 100644
--- a/avahi-common/watch.h
+++ b/avahi-common/watch.h
@@ -29,9 +29,7 @@
 
 #include <avahi-common/cdecl.h>
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_BEGIN
-#endif
 
 /** An I/O watch object */
 typedef struct AvahiWatch AvahiWatch;
@@ -95,9 +93,7 @@ struct AvahiPoll {
     void (*timeout_free)(AvahiTimeout *t);
 };
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
 AVAHI_C_DECL_END
-#endif
 
 #endif