Doxygen updates

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@7814 65c4cc65-6c06-0410-ace0-fbb531ad65f3

dns.c

@@ -1,7 +1,7 @@
 /*
  * Asterisk -- An open source telephony toolkit.
  *
- * Copyright (C) 1999 - 2005 Thorsten Lockert
+ * Copyright (C) 1999 - 2006 Thorsten Lockert
  *
  * Written by Thorsten Lockert <tholo@trollphone.org>
  *
@@ -44,40 +44,40 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 #define MAX_SIZE 4096
 
 typedef struct {
-	unsigned	id :16;		/* query identification number */
+	unsigned	id :16;		/*!< query identification number */
 #if __BYTE_ORDER == __BIG_ENDIAN
 			/* fields in third byte */
-	unsigned	qr: 1;		/* response flag */
-	unsigned	opcode: 4;	/* purpose of message */
-	unsigned	aa: 1;		/* authoritive answer */
-	unsigned	tc: 1;		/* truncated message */
-	unsigned	rd: 1;		/* recursion desired */
+	unsigned	qr: 1;		/*!< response flag */
+	unsigned	opcode: 4;	/*!< purpose of message */
+	unsigned	aa: 1;		/*!< authoritive answer */
+	unsigned	tc: 1;		/*!< truncated message */
+	unsigned	rd: 1;		/*!< recursion desired */
 			/* fields in fourth byte */
-	unsigned	ra: 1;		/* recursion available */
-	unsigned	unused :1;	/* unused bits (MBZ as of 4.9.3a3) */
-	unsigned	ad: 1;		/* authentic data from named */
-	unsigned	cd: 1;		/* checking disabled by resolver */
-	unsigned	rcode :4;	/* response code */
+	unsigned	ra: 1;		/*!< recursion available */
+	unsigned	unused :1;	/*!< unused bits (MBZ as of 4.9.3a3) */
+	unsigned	ad: 1;		/*!< authentic data from named */
+	unsigned	cd: 1;		/*!< checking disabled by resolver */
+	unsigned	rcode :4;	/*!< response code */
 #endif
 #if __BYTE_ORDER == __LITTLE_ENDIAN || __BYTE_ORDER == __PDP_ENDIAN
 			/* fields in third byte */
-	unsigned	rd :1;		/* recursion desired */
-	unsigned	tc :1;		/* truncated message */
-	unsigned	aa :1;		/* authoritive answer */
-	unsigned	opcode :4;	/* purpose of message */
-	unsigned	qr :1;		/* response flag */
+	unsigned	rd :1;		/*!< recursion desired */
+	unsigned	tc :1;		/*!< truncated message */
+	unsigned	aa :1;		/*!< authoritive answer */
+	unsigned	opcode :4;	/*!< purpose of message */
+	unsigned	qr :1;		/*!< response flag */
 			/* fields in fourth byte */
-	unsigned	rcode :4;	/* response code */
-	unsigned	cd: 1;		/* checking disabled by resolver */
-	unsigned	ad: 1;		/* authentic data from named */
-	unsigned	unused :1;	/* unused bits (MBZ as of 4.9.3a3) */
-	unsigned	ra :1;		/* recursion available */
+	unsigned	rcode :4;	/*!< response code */
+	unsigned	cd: 1;		/*!< checking disabled by resolver */
+	unsigned	ad: 1;		/*!< authentic data from named */
+	unsigned	unused :1;	/*!< unused bits (MBZ as of 4.9.3a3) */
+	unsigned	ra :1;		/*!< recursion available */
 #endif
 			/* remaining bytes */
-	unsigned	qdcount :16;	/* number of question entries */
-	unsigned	ancount :16;	/* number of answer entries */
-	unsigned	nscount :16;	/* number of authority entries */
-	unsigned	arcount :16;	/* number of resource entries */
+	unsigned	qdcount :16;	/*!< number of question entries */
+	unsigned	ancount :16;	/*!< number of answer entries */
+	unsigned	nscount :16;	/*!< number of authority entries */
+	unsigned	arcount :16;	/*!< number of resource entries */
 } dns_HEADER;
 
 struct dn_answer {
@@ -110,7 +110,7 @@ static int skip_name(char *s, int len)
 	return x;
 }
 
-/*--- dns_parse_answer: Parse DNS lookup result, call callback */
+/*! \brief Parse DNS lookup result, call callback */
 static int dns_parse_answer(void *context,
 	int class, int type, char *answer, int len,
 	int (*callback)(void *context, char *answer, int len, char *fullanswer))
@@ -182,7 +182,10 @@ AST_MUTEX_DEFINE_STATIC(res_lock);
 #endif
 #endif
 
-/*--- ast_search_dns: Lookup record in DNS */
+/*! \brief Lookup record in DNS 
+\note Asterisk DNS is synchronus at this time. This means that if your DNS does
+not work properly, Asterisk might not start properly or a channel may lock.
+*/
 int ast_search_dns(void *context,
 	   const char *dname, int class, int type,
 	   int (*callback)(void *context, char *answer, int len, char *fullanswer))

include/asterisk/dns.h

@@ -26,12 +26,14 @@
 
 struct ast_channel;
 
-/*!	\brief	Perform DNS lookup (used by enum and SRV lookups) 
+/*!	\brief	Perform DNS lookup (used by DNS, enum and SRV lookups) 
 	\param	context
 	\param	dname	Domain name to lookup (host, SRV domain, TXT record name)
 	\param	class	Record Class (see "man res_search")
 	\param	type	Record type (see "man res_search")
 	\param	callback Callback function for handling DNS result
+	\note   Asterisk DNS is synchronus at this time. This means that if your DNS
+		services does not work, Asterisk may lock while waiting for response.
 */
 extern int ast_search_dns(void *context, const char *dname, int class, int type,
 	 int (*callback)(void *context, char *answer, int len, char *fullanswer));