Documentation updates

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

diff --git a/avahi-common/Makefile.am b/avahi-common/Makefile.am
index 20eaee3eb398005cebaee4da372a4b3866c9652d..d91343b317eb798798c7c9df8ebdfdd7acb4b8c0 100644 (file)
--- 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 8056ac97bc5df7b1000deee6bd2957b3c370da1e..60495a327c71ab1c594e6c09e8c539f565c13332 100644 (file)
--- 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 a40126ddca12359f0c4c5f23b46429263e26a539..ca462c8bdd3e23a1d7e4ed3400a610d0abfb4e9d 100644 (file)
--- 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 b21d1fd83bdd20639cb0c6fbd1453480fe70990d..facd7b2f13bfbf6f71c32743623cf5661f864445 100644 (file)
--- 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 7c96b2325e8e26ccb0be38c7c692c8edd48ef1ca..fff11f0f3374dffcf13ef09a7317d5d66635919e 100644 (file)
--- 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 4a94be12a931e2a31d610f20bc03fc81eeeba964..eed7af48ef078a9a9309c3361d3c612b8ca865f6 100644 (file)
--- 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 27256e66c4adbc8418edff29bd94a0de9047bcc3..223ba021ea7045e4315886c370572c7a7e4c6af4 100644 (file)
--- 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 11ac9cfb3478a52d6a478b25cb998a1f72287f6c..2dd740e10e2525528b2bb864ef4c7f8ec2b716b9 100644 (file)
--- 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 78cffb47a064c7ddfea24607547a799dff681283..56bf5258b819e984f5fb963597cc0d0d13aa04c7 100644 (file)
--- 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

diff --git a/doxygen.cfg b/doxygen.cfg
index 8ec1080b7268e2f2ff9981d308c824f81e2f21bd..0e2c6be1343141ed144675ac7335446d06339fa5 100644 (file)
--- a/doxygen.cfg
+++ b/doxygen.cfg
@@ -67,7 +67,7 @@ WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = $(SRCDIR)/avahi-common/cdecl.h $(SRCDIR)/avahi-core/core.h $(SRCDIR)/avahi-common/address.h $(SRCDIR)/avahi-core/rr.h $(SRCDIR)/avahi-common/strlst.h $(SRCDIR)/avahi-common/alternative.h $(SRCDIR)/avahi-core/log.h $(SRCDIR)/avahi-common/defs.h $(SRCDIR)/avahi-client/client.h $(SRCDIR)/avahi-common/error.h $(SRCDIR)/avahi-common/util.h $(SRCDIR)/avahi-common/malloc.h $(SRCDIR)/avahi-common/util.h
+INPUT                  = $(SRCDIR)/avahi-common/cdecl.h $(SRCDIR)/avahi-core/core.h $(SRCDIR)/avahi-common/address.h $(SRCDIR)/avahi-core/rr.h $(SRCDIR)/avahi-common/strlst.h $(SRCDIR)/avahi-common/alternative.h $(SRCDIR)/avahi-core/log.h $(SRCDIR)/avahi-common/defs.h $(SRCDIR)/avahi-client/client.h $(SRCDIR)/avahi-common/error.h $(SRCDIR)/avahi-common/malloc.h $(SRCDIR)/avahi-common/domain.h
 FILE_PATTERNS          =
 RECURSIVE              = NO
 EXCLUDE                =