Doxygen additions, corrections

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

include/asterisk/ael_structs.h

@@ -1,3 +1,27 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 1999 - 2007, Digium, Inc.
+ *
+ * Mark Spencer <markster@digium.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+/*! \file
+ * \brief Structures for AEL - the Asterisk extension language
+ *
+ * \ref pbx_ael.c
+ */
+
 #ifndef _ASTERISK_AEL_STRUCTS_H
 #define _ASTERISK_AEL_STRUCTS_H
 
@@ -22,8 +46,7 @@
 #  endif
 
 
-typedef enum 
-{
+typedef enum {
 	PV_WORD, /* an ident, string, name, label, etc. A user-supplied string. */ /* 0 */
 	PV_MACRO,             /* 1 */
 	PV_CONTEXT,           /* 2 */

include/asterisk/config.h

@@ -33,6 +33,8 @@ struct ast_config;
 
 struct ast_category;
 
+/*! \brief Structure for variables, used for configurations and for channel variables 
+*/
 struct ast_variable {
 	char *name;
 	char *value;
@@ -50,6 +52,7 @@ typedef struct ast_variable *realtime_var_get(const char *database, const char *
 typedef struct ast_config *realtime_multi_get(const char *database, const char *table, va_list ap);
 typedef int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
 
+/*! \brief Configuration engine structure, used to define realtime drivers */
 struct ast_config_engine {
 	char *name;
 	config_load_func *load_func;

include/asterisk/doxyref.h

@@ -16,7 +16,7 @@
  * at the top of the source tree.
  */
 
-/* \file This file generates Doxygen pages from files in the /doc
+/*! \file This file generates Doxygen pages from files in the /doc
  directory of the Asterisk source code tree 
  */
 

include/asterisk/http.h

@@ -147,6 +147,7 @@ int ssl_setup(struct tls_config *cfg);
 */
 typedef struct ast_str *(*ast_http_callback)(struct sockaddr_in *requestor, const char *uri, struct ast_variable *params, int *status, char **title, int *contentlength);
 
+/*! \brief Definition of a URI reachable in the embedded HTTP server */
 struct ast_http_uri {
 	AST_LIST_ENTRY(ast_http_uri) entry;
 	const char *description;

include/asterisk/jingle.h

@@ -16,6 +16,15 @@
  * at the top of the source tree.
  */
 
+/*! \file
+ * \brief Jingle definitions for chan_jingle
+ *
+ * \ref chan_jingle.c
+ *
+ * \author Matt O'Gorman <mogorman@digium.com>
+ */
+
+
 #ifndef _ASTERISK_JINGLE_H
 #define _ASTERISK_JINGLE_H
 

include/asterisk/utils.h

@@ -39,8 +39,8 @@
 #include "asterisk/logger.h"
 #include "asterisk/compiler.h"
 
-/*! \note
- \verbatim
+/*! 
+\note \verbatim
    Note:
    It is very important to use only unsigned variables to hold
    bit flags, as otherwise you can fall prey to the compiler's
@@ -141,6 +141,8 @@ extern unsigned int __unsigned_int_flags_dummy;
 
 #define AST_FLAGS_ALL UINT_MAX
 
+/*! \brief Structure used to handle boolean flags 
+*/
 struct ast_flags {
 	unsigned int flags;
 };
@@ -150,22 +152,21 @@ struct ast_hostent {
 	char buf[1024];
 };
 
+/*! \brief Thread-safe gethostbyname function to use in Asterisk */
 struct hostent *ast_gethostbyname(const char *host, struct ast_hostent *hp);
 
-/* ast_md5_hash 
-	\brief Produces MD5 hash based on input string */
+/*!  \brief Produces MD5 hash based on input string */
 void ast_md5_hash(char *output, char *input);
-/* ast_sha1_hash
-	\brief Produces SHA1 hash based on input string */
+/*! \brief Produces SHA1 hash based on input string */
 void ast_sha1_hash(char *output, char *input);
 
 int ast_base64encode_full(char *dst, const unsigned char *src, int srclen, int max, int linebreaks);
 int ast_base64encode(char *dst, const unsigned char *src, int srclen, int max);
 int ast_base64decode(unsigned char *dst, const char *src, int max);
 
-/*! ast_uri_encode
-	\brief Turn text string to URI-encoded %XX version 
- 	At this point, we're converting from ISO-8859-x (8-bit), not UTF8
+/*!  \brief Turn text string to URI-encoded %XX version 
+
+\note 	At this point, we're converting from ISO-8859-x (8-bit), not UTF8
 	as in the SIP protocol spec 
 	If doreserved == 1 we will convert reserved characters also.
 	RFC 2396, section 2.4
@@ -238,7 +239,7 @@ const char *ast_inet_ntoa(struct in_addr ia);
 int ast_utils_init(void);
 int ast_wait_for_input(int fd, int ms);
 
-/*! ast_carefulwrite
+/*!
 	\brief Try to write string, but wait no more than ms milliseconds
 	before timing out.
 
@@ -249,7 +250,7 @@ int ast_wait_for_input(int fd, int ms);
 */
 int ast_carefulwrite(int fd, char *s, int len, int timeoutms);
 
-/*! Compares the source address and port of two sockaddr_in */
+/*! \brief Compares the source address and port of two sockaddr_in */
 static force_inline int inaddrcmp(const struct sockaddr_in *sin1, const struct sockaddr_in *sin2)
 {
 	return ((sin1->sin_addr.s_addr != sin2->sin_addr.s_addr) 

include/asterisk/zapata.h

@@ -17,6 +17,11 @@
  * for less than ten lines of preprocessor directives...
  */
 
+/*! \file
+ * \brief Stub to find zaptel headers
+ */
+
+
 /*
  * Stub to find the zaptel headers. The configure script will
  * define HAVE_ZAPTEL_VERSION according to what it has found.