Documentation updates

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

9 files changed, 65 insertions, 17 deletions

diff --git a/avahi-common/Makefile.am b/avahi-common/Makefile.am
index 20eaee3..d91343b 100644
--- a/avahi-common/Makefile.am
+++ b/avahi-common/Makefile.am
@@ -37,11 +37,12 @@ avahi_commoninclude_HEADERS = \
 	defs.h \
 	malloc.h
 
+noinst_HEADERS = llist.h
+
 if ENABLE_DBUS
-avahi_commoninclude_HEADERS += dbus.h
+noinst_HEADERS += dbus.h
 endif
 
-noinst_HEADERS = llist.h
 
 noinst_PROGRAMS = \
 	strlst-test \
diff --git a/avahi-common/address.h b/avahi-common/address.h
index 8056ac9..60495a3 100644
--- a/avahi-common/address.h
+++ b/avahi-common/address.h
@@ -22,13 +22,13 @@
   USA.
 ***/
 
+/** \file address.h Definitions and functions to manipulate IP addresses. */
+
 #include <sys/socket.h>
 #include <inttypes.h>
 
 #include <avahi-common/cdecl.h>
 
-/** \file address.h Defintions and functions to manipulate IP addresses. */
-
 AVAHI_C_DECL_BEGIN
 
 /** Protocol family specification, takes the values AVAHI_INET, AVAHI_INET6, AVAHI_UNSPEC */
diff --git a/avahi-common/cdecl.h b/avahi-common/cdecl.h
index a40126d..ca462c8 100644
--- a/avahi-common/cdecl.h
+++ b/avahi-common/cdecl.h
@@ -22,7 +22,6 @@
   USA.
 ***/
 
-
 /** \file cdecl.h C++ compatibility */
 
 #ifdef __cplusplus
diff --git a/avahi-common/dbus.h b/avahi-common/dbus.h
index b21d1fd..facd7b2 100644
--- a/avahi-common/dbus.h
+++ b/avahi-common/dbus.h
@@ -22,6 +22,10 @@
   USA.
 ***/
 
+/** \file dbus.h Some definitions for the DBUS interface */
+
+#include <avahi-common/cdecl.h>
+
 AVAHI_C_DECL_BEGIN
 
 #define AVAHI_DBUS_NAME "org.freedesktop.Avahi"
diff --git a/avahi-common/defs.h b/avahi-common/defs.h
index 7c96b23..fff11f0 100644
--- a/avahi-common/defs.h
+++ b/avahi-common/defs.h
@@ -22,6 +22,8 @@
   USA.
 ***/
 
+/** \file defs.h Some common definitions */
+
 #include <avahi-common/cdecl.h>
 
 AVAHI_C_DECL_BEGIN
diff --git a/avahi-common/domain.h b/avahi-common/domain.h
index 4a94be1..eed7af4 100644
--- a/avahi-common/domain.h
+++ b/avahi-common/domain.h
@@ -22,6 +22,9 @@
   USA.
 ***/
 
+/** \file domain.h Domain name handling functions */
+
+
 #include <inttypes.h>
 #include <sys/types.h>
 
@@ -29,28 +32,49 @@
 
 AVAHI_C_DECL_BEGIN
 
-char *avahi_normalize_name(const char *s); /* avahi_free() the result! */
-char *avahi_get_host_name(void); /* avahi_free() the result! */
+/** Normalize a domain name into canonical form. This drops trailing
+ * dots and removes useless backslash escapes. avahi_free() the
+ * result! */
+char *avahi_normalize_name(const char *s);
+
+/** Return the local host name. avahi_free() the result! */
+char *avahi_get_host_name(void); 
 
+/** Return 1 when the specified domain names are equal, 0 otherwise */
 int avahi_domain_equal(const char *a, const char *b);
+
+/** Do a binary comparison of to specified domain names, returnen -1, 0, or 1, depending on the error. */
 int avahi_binary_domain_cmp(const char *a, const char *b);
 
-/* Read the first label from the textual domain name *name, unescape
+/** 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);
 
-/* Escape the domain name in *src and write it to *ret_name */
+/** Escape the domain name in *src and write it to *ret_name */
 char *avahi_escape_label(const uint8_t* src, size_t src_length, char **ret_name, size_t *ret_size);
 
+/** Return some kind of hash value for a string */
 unsigned avahi_strhash(const char *p);
+
+/** Return some kind of hash value for a domain */
 unsigned avahi_domain_hash(const char *s);
 
+/** Return 1 when the specified string contains a valid service type, 0 otherwise */
 int avahi_valid_service_type(const char *t);
+
+/** Return 1 when the specified string contains a valid domain name, 0 otherwise */
 int avahi_valid_domain_name(const char *t);
+
+/** Return 1 when the specified string contains a valid service name, 0 otherwise */
 int avahi_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 */
 int avahi_valid_host_name(const char *t);
 
+/** Change every character in the string to upper case (ASCII), return a pointer to the string */
 char *avahi_strup(char *s);
+
+/** Change every character in the string to lower case (ASCII), return a pointer to the string */
 char *avahi_strdown(char *s);
 
 AVAHI_C_DECL_END
diff --git a/avahi-common/error.h b/avahi-common/error.h
index 27256e6..223ba02 100644
--- a/avahi-common/error.h
+++ b/avahi-common/error.h
@@ -22,6 +22,12 @@
   USA.
 ***/
 
+/** \file error.h Error codes and auxiliary functions */
+
+#include <avahi-common/cdecl.h>
+
+AVAHI_C_DECL_BEGIN
+
 /** Error codes used by avahi */
 enum { 
     AVAHI_OK = 0,                          /**< OK */
@@ -54,4 +60,6 @@ enum {
 /** Return a human readable error string for the specified error code */
 const char *avahi_strerror(int error);
 
+AVAHI_C_DECL_END
+
 #endif
diff --git a/avahi-common/malloc.h b/avahi-common/malloc.h
index 11ac9cf..2dd740e 100644
--- a/avahi-common/malloc.h
+++ b/avahi-common/malloc.h
@@ -22,9 +22,15 @@
   USA.
 ***/
 
+/** \file malloc.h Memory allocation */
+
 #include <sys/types.h>
 #include <stdarg.h>
 
+#include <avahi-common/cdecl.h>
+
+AVAHI_C_DECL_BEGIN
+
 /** Allocate some memory, just like the libc malloc() */
 void *avahi_malloc(size_t size);
 
@@ -43,14 +49,16 @@ void *avahi_realloc(void *p, size_t size);
 /** Same as avahi_new() but set the memory to zero */
 #define avahi_new0(type, n) (type*) avahi_malloc0(n*sizeof(type))
 
-/* Just like libc's strdup() */
+/** Just like libc's strdup() */
 char *avahi_strdup(const char *s);
 
-/* Just like libc's strndup() */
+/** Just like libc's strndup() */
 char *avahi_strndup(const char *s, size_t l); 
 
 /** Wraps allocator functions */
 typedef struct AvahiAllocator AvahiAllocator;
+
+/** Wraps allocator functions */
 struct AvahiAllocator {
     void* (*malloc)(size_t size);     
     void (*free)(void *p);           
@@ -58,18 +66,20 @@ struct AvahiAllocator {
     void* (*calloc)(size_t nmemb, size_t size);   /**< May be NULL */
 };
 
-/* Change the allocator. May be NULL to return to default (libc)
+/** Change the allocator. May be NULL to return to default (libc)
  * allocators. The structure is not copied! */
 void avahi_set_allocator(const AvahiAllocator *a);
 
-
-char *avahi_strdup_vprintf(const char *fmt, va_list ap);
-
 #ifdef __GNUC__
 char *avahi_strdup_printf(const char *fmt, ... )  __attribute__ ((format(printf, 1, 2)));
 #else
+/** Like sprintf() but store the result in a freshly allocated buffer. Free this with avahi_free() */
 char *avahi_strdup_printf(const char *fmt, ... );
 #endif
 
+/** Same as avahi_strdup_printf() but take a va_list instead of varargs */
+char *avahi_strdup_vprintf(const char *fmt, va_list ap);
+
+AVAHI_C_DECL_END
 
 #endif
diff --git a/avahi-common/strlst.h b/avahi-common/strlst.h
index 78cffb4..56bf525 100644
--- a/avahi-common/strlst.h
+++ b/avahi-common/strlst.h
@@ -22,14 +22,14 @@
   USA.
 ***/
 
+/** \file strlst.h Implementation of a data type to store lists of strings */
+
 #include <sys/types.h>
 #include <inttypes.h>
 #include <stdarg.h>
 
 #include <avahi-common/cdecl.h>
 
-/** \file strlst.h Implementation of a data type to store lists of strings */
-
 AVAHI_C_DECL_BEGIN
 
 /** Linked list of strings that can contain any number of binary