(closes issue #10271)

Reported by: snuffy
Patches:
      doxygen-updates.diff uploaded by snuffy (license 35)

Another big batch of doxygen documentation updates


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

channels/chan_sip.c

@@ -13514,7 +13514,7 @@ static void handle_response(struct sip_pvt *p, int resp, char *rest, struct sip_
 					if (p->owner)
 						ast_queue_control(p->owner, AST_CONTROL_BUSY);
 					break;
-				case 482: /*
+				case 482: /*!
 					\note SIP is incapable of performing a hairpin call, which
 					is yet another failure of not having a layer 2 (again, YAY
 					 IETF for thinking ahead).  So we treat this as a call

include/asterisk.h

@@ -105,9 +105,10 @@ struct ast_module;
  * \note Modules are reloaded using their reload() functions, not unloading
  * them and loading them again.
  * 
- * \return Zero if the specified module was not found, 1 if the module was
- * found but cannot be reloaded, -1 if a reload operation is already in
- * progress, and 2 if the specfied module was found and reloaded.
+ * \return 0 if the specified module was not found.
+ * \retval 1 if the module was found but cannot be reloaded.
+ * \retval -1 if a reload operation is already in progress.
+ * \retval 2 if the specfied module was found and reloaded.
  */
 int ast_module_reload(const char *name);
 
@@ -115,7 +116,8 @@ int ast_module_reload(const char *name);
  * \brief Register a function to be executed before Asterisk exits.
  * \param func The callback function to use.
  *
- * \return Zero on success, -1 on error.
+ * \retval 0 on success.
+ * \retval -1 on error.
  */
 int ast_register_atexit(void (*func)(void));
 

include/asterisk/doxyref.h

@@ -551,4 +551,3 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  *  \arg \link Config_ami Configuration file \endlink
  *  \verbinclude ajam.txt
  */
-

include/asterisk/file.h

@@ -107,7 +107,7 @@ struct ast_format {
 	 * When allocating a buffer, remember to leave AST_FRIENDLY_OFFSET
 	 * spare bytes at the bginning.
 	 */
-	int buf_size;			/* size of frame buffer, if any, aligned to 8 bytes. */
+	int buf_size;			/*!< size of frame buffer, if any, aligned to 8 bytes. */
 	int desc_size;			/*!< size of private descriptor, if any */
 
 	struct ast_module *module;
@@ -134,9 +134,9 @@ struct ast_filestream {
 	int lasttimeout;
 	struct ast_channel *owner;
 	FILE *f;
-	struct ast_frame fr;	/* frame produced by read, typically */
-	char *buf;		/* buffer pointed to by ast_frame; */
-	void *private;	/* pointer to private buffer */
+	struct ast_frame fr;	/*!< frame produced by read, typically */
+	char *buf;		/*!< buffer pointed to by ast_frame; */
+	void *private;	/*!< pointer to private buffer */
 };
 
 #define SEEK_FORCECUR	10

include/jitterbuf.h

@@ -21,18 +21,18 @@ extern "C" {
 #endif
 
 /* configuration constants */
-	/* Number of historical timestamps to use in calculating jitter and drift */
+	/*! Number of historical timestamps to use in calculating jitter and drift */
 #define JB_HISTORY_SZ		500	
-	/* what percentage of timestamps should we drop from the history when we examine it;
+	/*! what percentage of timestamps should we drop from the history when we examine it;
 	 * this might eventually be something made configurable */
 #define JB_HISTORY_DROPPCT	3
-	/* the maximum droppct we can handle (say it was configurable). */
+	/*! the maximum droppct we can handle (say it was configurable). */
 #define JB_HISTORY_DROPPCT_MAX	4
-	/* the size of the buffer we use to keep the top and botton timestamps for dropping */
+	/*! the size of the buffer we use to keep the top and botton timestamps for dropping */
 #define JB_HISTORY_MAXBUF_SZ	JB_HISTORY_SZ * JB_HISTORY_DROPPCT_MAX / 100 
-	/* amount of additional jitterbuffer adjustment  */
+	/*! amount of additional jitterbuffer adjustment  */
 #define JB_TARGET_EXTRA 40
-	/* ms between growing and shrinking; may not be honored if jitterbuffer runs out of space */
+	/*! ms between growing and shrinking; may not be honored if jitterbuffer runs out of space */
 #define JB_ADJUST_DELAY 40
 
 enum jb_return_code {
@@ -55,36 +55,36 @@ enum jb_frame_type {
 
 typedef struct jb_conf {
 	/* settings */
-	long max_jitterbuf;	/* defines a hard clamp to use in setting the jitter buffer delay */
- 	long resync_threshold;  /* the jb will resync when delay increases to (2 * jitter) + this param */
-	long max_contig_interp; /* the max interp frames to return in a row */
-	long target_extra ;      /* amount of additional jitterbuffer adjustment, overrides JB_TARGET_EXTRA */
+	long max_jitterbuf;	/*!< defines a hard clamp to use in setting the jitter buffer delay */
+ 	long resync_threshold;  /*!< the jb will resync when delay increases to (2 * jitter) + this param */
+	long max_contig_interp; /*!< the max interp frames to return in a row */
+	long target_extra ;      /*!< amount of additional jitterbuffer adjustment, overrides JB_TARGET_EXTRA */
 } jb_conf;
 
 typedef struct jb_info {
 	jb_conf conf;
 
 	/* statistics */
-	long frames_in;  	/* number of frames input to the jitterbuffer.*/
-	long frames_out;  	/* number of frames output from the jitterbuffer.*/
-	long frames_late; 	/* number of frames which were too late, and dropped.*/
-	long frames_lost; 	/* number of missing frames.*/
-	long frames_dropped; 	/* number of frames dropped (shrinkage) */
-	long frames_ooo; 	/* number of frames received out-of-order */
-	long frames_cur; 	/* number of frames presently in jb, awaiting delivery.*/
-	long jitter; 		/* jitter measured within current history interval*/
-	long min;		/* minimum lateness within current history interval */
-	long current; 		/* the present jitterbuffer adjustment */
-	long target; 		/* the target jitterbuffer adjustment */
-	long losspct; 		/* recent lost frame percentage (* 1000) */
-	long next_voice_ts;	/* the ts of the next frame to be read from the jb - in receiver's time */
-	long last_voice_ms;	/* the duration of the last voice frame */
-	long silence_begin_ts;	/* the time of the last CNG frame, when in silence */
-	long last_adjustment;   /* the time of the last adjustment */
- 	long last_delay;        /* the last now added to history */
- 	long cnt_delay_discont;	/* the count of discontinuous delays */
- 	long resync_offset;     /* the amount to offset ts to support resyncs */
-	long cnt_contig_interp; /* the number of contiguous interp frames returned */
+	long frames_in;  	/*!< number of frames input to the jitterbuffer.*/
+	long frames_out;  	/*!< number of frames output from the jitterbuffer.*/
+	long frames_late; 	/*!< number of frames which were too late, and dropped.*/
+	long frames_lost; 	/*!< number of missing frames.*/
+	long frames_dropped; 	/*!< number of frames dropped (shrinkage) */
+	long frames_ooo; 	/*!< number of frames received out-of-order */
+	long frames_cur; 	/*!< number of frames presently in jb, awaiting delivery.*/
+	long jitter; 		/*!< jitter measured within current history interval*/
+	long min;		/*!< minimum lateness within current history interval */
+	long current; 		/*!< the present jitterbuffer adjustment */
+	long target; 		/*!< the target jitterbuffer adjustment */
+	long losspct; 		/*!< recent lost frame percentage (* 1000) */
+	long next_voice_ts;	/*!< the ts of the next frame to be read from the jb - in receiver's time */
+	long last_voice_ms;	/*!< the duration of the last voice frame */
+	long silence_begin_ts;	/*!< the time of the last CNG frame, when in silence */
+	long last_adjustment;   /*!< the time of the last adjustment */
+ 	long last_delay;        /*!< the last now added to history */
+ 	long cnt_delay_discont;	/*!< the count of discontinuous delays */
+ 	long resync_offset;     /*!< the amount to offset ts to support resyncs */
+	long cnt_contig_interp; /*!< the number of contiguous interp frames returned */
 } jb_info;
 
 typedef struct jb_frame {
@@ -99,15 +99,15 @@ typedef struct jitterbuf {
 	jb_info info;
 
 	/* history */
-	long history[JB_HISTORY_SZ];   		/* history */
-	int  hist_ptr;				/* points to index in history for next entry */
-	long hist_maxbuf[JB_HISTORY_MAXBUF_SZ];	/* a sorted buffer of the max delays (highest first) */
-	long hist_minbuf[JB_HISTORY_MAXBUF_SZ];	/* a sorted buffer of the min delays (lowest first) */
-	int  hist_maxbuf_valid;			/* are the "maxbuf"/minbuf valid? */
-	unsigned int dropem:1;                  /* flag to indicate dropping frames (overload) */
-
-	jb_frame *frames; 		/* queued frames */
-	jb_frame *free; 		/* free frames (avoid malloc?) */
+	long history[JB_HISTORY_SZ];   		/*!< history */
+	int  hist_ptr;				/*!< points to index in history for next entry */
+	long hist_maxbuf[JB_HISTORY_MAXBUF_SZ];	/*!< a sorted buffer of the max delays (highest first) */
+	long hist_minbuf[JB_HISTORY_MAXBUF_SZ];	/*!< a sorted buffer of the min delays (lowest first) */
+	int  hist_maxbuf_valid;			/*!< are the "maxbuf"/minbuf valid? */
+	unsigned int dropem:1;                  /*!< flag to indicate dropping frames (overload) */
+
+	jb_frame *frames; 		/*!< queued frames */
+	jb_frame *free; 		/*!< free frames (avoid malloc?) */
 } jitterbuf;
 
 
@@ -146,10 +146,10 @@ enum jb_return_code jb_getall(jitterbuf *jb, jb_frame *frameout);
  * This value may change as frames are added (esp non-audio frames) */
 long			jb_next(jitterbuf *jb);
 
-/* get jitterbuf info: only "statistics" may be valid */
+/*! get jitterbuf info: only "statistics" may be valid */
 enum jb_return_code jb_getinfo(jitterbuf *jb, jb_info *stats);
 
-/* set jitterbuf conf */
+/*! set jitterbuf conf */
 enum jb_return_code jb_setconf(jitterbuf *jb, jb_conf *conf);
 
 typedef 		void (*jb_output_function_t)(const char *fmt, ...);

main/asterisk.c

@@ -153,9 +153,9 @@ int daemon(int, int);  /* defined in libresolv of all places */
                 "production installations.\n");
 
 /*! \defgroup main_options Main Configuration Options
- \brief Main configuration options from \ref Config_ast "asterisk.conf" or 
-  the operating system command line when starting Asterisk 
-  Some of them can be changed in the CLI 
+ * \brief Main configuration options from asterisk.conf or OS command line on starting Asterisk.
+ * \arg \ref Config_ast "asterisk.conf"
+ * \note Some of them can be changed in the CLI 
  */
 /*! @{ */
 

main/devicestate.c

@@ -93,7 +93,7 @@
  *	and reported back.
  *
  *	- Extension states
- *		\arg \ref ENUM ast_extension_states
+ *		\arg \ref AstENUM ast_extension_states
  *		\arg \ref pbx.c 
  *		\arg \ref pbx.h 
  *	- Structures

main/enum.c

@@ -362,7 +362,7 @@ static int enum_callback(void *context, unsigned char *answer, int len, unsigned
 	return 0;
 }
 
-/*! \brief ENUM lookup */
+/* ENUM lookup */
 int ast_get_enum(struct ast_channel *chan, const char *number, char *dst, int dstlen, char *tech, int techlen, char* suffix, char* options, unsigned int record, struct enum_context **argcontext)
 {
 	struct enum_context *context;
@@ -532,9 +532,7 @@ int ast_get_enum(struct ast_channel *chan, const char *number, char *dst, int ds
 	return ret;
 }
 
-/*! \brief Get TXT record from DNS.
-	Really has nothing to do with enum, but anyway...
- */
+/* Get TXT record from DNS. Really has nothing to do with enum, but anyway... */
 int ast_get_txt(struct ast_channel *chan, const char *number, char *dst, int dstlen, char *tech, int techlen, char *txt, int txtlen)
 {
 	struct enum_context context;

res/res_clioriginate.c

@@ -69,6 +69,15 @@ struct ast_cli_entry cli_cliorig[] = {
 	orig_help, complete_orig },
 };
 
+/*!
+ * \brief orginate a call from the CLI
+ * \param fd file descriptor for cli
+ * \param chan channel to create type/data
+ * \param app application you want to run
+ * \param appdata data for application
+ * \retval RESULT_SUCCESS on success.
+ * \retval RESULT_SHOWUSAGE on failure.
+*/
 static int orig_app(int fd, const char *chan, const char *app, const char *appdata)
 {
 	char *chantech;
@@ -91,6 +100,14 @@ static int orig_app(int fd, const char *chan, const char *app, const char *appda
 	return RESULT_SUCCESS;
 }
 
+/*!
+ * \brief orginate from extension
+ * \param fd file descriptor for cli
+ * \param chan channel to create type/data
+ * \param data contains exten\@context
+ * \retval RESULT_SUCCESS on success.
+ * \retval RESULT_SHOWUSAGE on failure.
+*/
 static int orig_exten(int fd, const char *chan, const char *data)
 {
 	char *chantech;
@@ -122,6 +139,14 @@ static int orig_exten(int fd, const char *chan, const char *data)
 	return RESULT_SUCCESS;
 }
 
+/*!
+ * \brief handle for orgination app or exten.
+ * \param fd file descriptor
+ * \param argc no of arguements
+ * \param argv contains either application or extension arguements
+ * \retval RESULT_SUCCESS on success.
+ * \retval RESULT_SHOWUSAGE on failure.
+*/
 static int handle_orig(int fd, int argc, char *argv[])
 {
 	int res;
@@ -144,6 +169,15 @@ static int handle_orig(int fd, int argc, char *argv[])
 	return res;
 }
 
+/*!
+ * \brief complete suggestions for orginate command
+ * \param line 
+ * \param word to be completed word
+ * \param pos position
+ * \param state
+ * \retval completed word
+ * \retval NULL on failure
+*/
 static char *complete_orig(const char *line, const char *word, int pos, int state)
 {
 	static char *choices[] = { "application", "extension", NULL };
@@ -160,12 +194,14 @@ static char *complete_orig(const char *line, const char *word, int pos, int stat
 	return ret;
 }
 
+/*! \brief Unload orginate module */
 static int unload_module(void)
 {
 	ast_cli_unregister_multiple(cli_cliorig, sizeof(cli_cliorig) / sizeof(struct ast_cli_entry));
 	return 0;
 }
 
+/*! \brief Load orginate module */
 static int load_module(void)
 {
 	ast_cli_register_multiple(cli_cliorig, sizeof(cli_cliorig) / sizeof(struct ast_cli_entry));

res/res_config_odbc.c

@@ -54,6 +54,18 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 #include "asterisk/res_odbc.h"
 #include "asterisk/utils.h"
 
+/*!
+ * \brief Excute an SQL query and return ast_variable list
+ * \param database
+ * \param table
+ * \param ap list containing one or more field/operator/value set
+ * Select database and preform query on table, prepare the sql statement
+ * Sub-in the values to the prepared statement and execute it. Return results
+ * as a ast_variable list.
+ *
+ * \retval var on success
+ * \retval NULL on failure
+*/
 static struct ast_variable *realtime_odbc(const char *database, const char *table, va_list ap)
 {
 	struct odbc_obj *obj;
@@ -204,6 +216,19 @@ static struct ast_variable *realtime_odbc(const char *database, const char *tabl
 	return var;
 }
 
+/*!
+ * \brief Excute an Select query and return ast_config list
+ * \param database
+ * \param table
+ * \param ap list containing one or more field/operator/value set
+ * Select database and preform query on table, prepare the sql statement
+ * Sub-in the values to the prepared statement and execute it. 
+ * Execute this prepared query against several ODBC connected databases.
+ * Return results as an ast_config variable.
+ *
+ * \retval var on success
+ * \retval NULL on failure
+*/
 static struct ast_config *realtime_multi_odbc(const char *database, const char *table, va_list ap)
 {
 	struct odbc_obj *obj;
@@ -360,6 +385,20 @@ static struct ast_config *realtime_multi_odbc(const char *database, const char *
 	return cfg;
 }
 
+/*!
+ * \brief Excute an UPDATE query
+ * \param database
+ * \param table
+ * \param keyfield where clause field
+ * \param lookup value of field for where clause
+ * \param ap list containing one or more field/value set(s)
+ * Update a database table, prepare the sql statement using keyfield and lookup
+ * control the number of records to change. All values to be changed are stored in ap list.
+ * Sub-in the values to the prepared statement and execute it.
+ *
+ * \retval number of rows affected
+ * \retval -1 on failure
+*/
 static int update_odbc(const char *database, const char *table, const char *keyfield, const char *lookup, va_list ap)
 {
 	struct odbc_obj *obj;

res/res_config_sqlite.c

@@ -20,7 +20,7 @@
  */
 
 /*!
- * \mainpage res_config_sqlite
+ * \page res_config_sqlite
  * 
  * \section intro_sec Presentation
  * 
@@ -232,56 +232,58 @@ struct rt_multi_cfg_entry_args {
 };
 
 /*!
- * Allocate a variable.
- * 
- * \param var	 the address of the variable to set (it will be allocated)
- * \param name	the name of the variable (for error handling)
+ * \brief Allocate a variable.
+ * \param var the address of the variable to set (it will be allocated)
+ * \param name the name of the variable (for error handling)
  * \param value the value to store in var
- * \return 1 if an allocation error occurred, 0 otherwise
+ * \retval 0 on success
+ * \retval 1 if an allocation error occurred
  */
 static int set_var(char **var, char *name, char *value);
 
 /*!
- * Load the configuration file.
+ * \brief Load the configuration file.
+ * \see unload_config()
  * 
  * This function sets dbfile, config_table, and cdr_table. It calls
  * check_vars() before returning, and unload_config() if an error occurred.
  * 
- * \return 1 if an error occurred, 0 otherwise
- * \see unload_config()
+ * \retval 0 on success
+ * \retval 1 if an error occurred
  */
 static int load_config(void);
 
 /*!
- * Free resources related to configuration.
- * 
+ * \brief Free resources related to configuration.
  * \see load_config()
  */
 static void unload_config(void);
 
 /*!
- * Asterisk callback function for CDR support.
+ * \brief Asterisk callback function for CDR support.
+ * \param cdr the CDR entry Asterisk sends us
  * 
  * Asterisk will call this function each time a CDR entry must be logged if
  * CDR support is enabled.
  * 
- * \param cdr the CDR entry Asterisk sends us
- * \return 1 if an error occurred, 0 otherwise
+ * \retval 0 on success
+ * \retval 1 if an error occurred
  */
 static int cdr_handler(struct ast_cdr *cdr);
 
 /*!
- * SQLite callback function for static configuration.
+ * \brief SQLite callback function for static configuration.
  * 
  * This function is passed to the SQLite engine as a callback function to
  * parse a row and store it in a struct ast_config object. It relies on
  * resulting rows	being sorted by category.
  * 
- * \param arg				 a pointer to a struct cfg_entry_args object
- * \param argc				number of columns
- * \param argv				values in the row
+ * \param arg a pointer to a struct cfg_entry_args object
+ * \param argc number of columns
+ * \param argv values in the row
  * \param columnNames names and types of the columns
- * \return 1 if an error occurred, 0 otherwise
+ * \retval 0 on success
+ * \retval 1 if an error occurred
  * \see cfg_entry_args
  * \see sql_get_config_table
  * \see config_handler()
@@ -289,17 +291,18 @@ static int cdr_handler(struct ast_cdr *cdr);
 static int add_cfg_entry(void *arg, int argc, char **argv, char **columnNames);
 
 /*!
- * Asterisk callback function for static configuration.
+ * \brief Asterisk callback function for static configuration.
  * 
  * Asterisk will call this function when it loads its static configuration,
  * which usually happens at startup and reload.
  * 
  * \param database the database to use (ignored)
- * \param table		the table to use
- * \param file		 the file to load from the database
- * \param cfg			the struct ast_config object to use when storing variables
+ * \param table the table to use
+ * \param file the file to load from the database
+ * \param cfg the struct ast_config object to use when storing variables
  * \param withcomments	Integer. Flag
- * \return NULL if an error occurred, cfg otherwise
+ * \retval cfg object
+ * \retval NULL if an error occurred
  * \see add_cfg_entry()
  */
 static struct ast_config * config_handler(const char *database,
@@ -307,7 +310,7 @@ static struct ast_config * config_handler(const char *database,
 	struct ast_config *cfg, int withcomments);
 
 /*!
- * Helper function to parse a va_list object into 2 dynamic arrays of
+ * \brief Helper function to parse a va_list object into 2 dynamic arrays of
  * strings, parameters and values.
  * 
  * ap must have the following format : param1 val1 param2 val2 param3 val3 ...
@@ -322,26 +325,27 @@ static struct ast_config * config_handler(const char *database,
  * is the responsibility of the caller to release the memory of these arrays.
  * It is considered an error that va_list has a null or odd number of strings.
  * 
- * \param ap				 the va_list object to parse
+ * \param ap the va_list object to parse
  * \param params_ptr where the address of the params array is stored
- * \param vals_ptr	 where the address of the vals array is stored
- * \return 0 if an error occurred, the number of elements in the arrays (which
- *				 have the same size) otherwise
+ * \param vals_ptr where the address of the vals array is stored
+ * \retval the number of elements in the arrays (which have the same size).
+ * \retval 0 if an error occurred.
  */
 static size_t get_params(va_list ap, const char ***params_ptr,
 	const char ***vals_ptr);
 
 /*!
- * SQLite callback function for RealTime configuration.
+ * \brief SQLite callback function for RealTime configuration.
  * 
  * This function is passed to the SQLite engine as a callback function to
  * parse a row and store it in a linked list of struct ast_variable objects.
  * 
- * \param arg				 a pointer to a struct rt_cfg_entry_args object
- * \param argc				number of columns
- * \param argv				values in the row
+ * \param arg a pointer to a struct rt_cfg_entry_args object
+ * \param argc number of columns
+ * \param argv values in the row
  * \param columnNames names and types of the columns
- * \return 1 if an error occurred, 0 otherwise
+ * \retval 0 on success.
+ * \retval 1 if an error occurred.
  * \see rt_cfg_entry_args
  * \see realtime_handler()
  */
@@ -360,25 +364,27 @@ static int add_rt_cfg_entry(void *arg, int argc, char **argv,
  * \param database the database to use (ignored)
  * \param table		the table to use
  * \param ap			 list of parameters and values to match
- * \return NULL if an error occurred, a linked list of struct ast_variable
- *				 objects otherwise
+ *
+ * \retval a linked list of struct ast_variable objects
+ * \retval NULL if an error occurred
  * \see add_rt_cfg_entry()
  */
 static struct ast_variable * realtime_handler(const char *database,
 	const char *table, va_list ap);
 
 /*!
- * SQLite callback function for RealTime configuration.
+ * \brief SQLite callback function for RealTime configuration.
  * 
  * This function performs the same actions as add_rt_cfg_entry() except
  * that the rt_multi_cfg_entry_args structure is designed to store
  * categories in addition of variables.
  * 
- * \param arg				 a pointer to a struct rt_multi_cfg_entry_args object
- * \param argc				number of columns
- * \param argv				values in the row
+ * \param arg a pointer to a struct rt_multi_cfg_entry_args object
+ * \param argc number of columns
+ * \param argv values in the row
  * \param columnNames names and types of the columns
- * \return 1 if an error occurred, 0 otherwise
+ * \retval 0 on success.
+ * \retval 1 if an error occurred.
  * \see rt_multi_cfg_entry_args
  * \see realtime_multi_handler()
  */
@@ -386,17 +392,18 @@ static int add_rt_multi_cfg_entry(void *arg, int argc, char **argv,
 	char **columnNames);
 
 /*!
- * Asterisk callback function for RealTime configuration.
+ * \brief Asterisk callback function for RealTime configuration.
  * 
  * This function performs the same actions as realtime_handler() except
  * that it can store variables per category, and can return several
  * categories.
  * 
  * \param database the database to use (ignored)
- * \param table		the table to use
- * \param ap			 list of parameters and values to match
- * \return NULL if an error occurred, a struct ast_config object storing
- *				 categories and variables
+ * \param table the table to use
+ * \param ap list of parameters and values to match
+ * \retval a struct ast_config object storing categories and variables.
+ * \retval NULL if an error occurred.
+ *
  * \see add_rt_multi_cfg_entry()
  */
 static struct ast_config * realtime_multi_handler(const char *database,
@@ -404,7 +411,7 @@ static struct ast_config * realtime_multi_handler(const char *database,
 	va_list ap);
 
 /*!
- * Asterisk callback function for RealTime configuration (variable
+ * \brief Asterisk callback function for RealTime configuration (variable
  * update).
  * 
  * Asterisk will call this function each time a variable has been modified
@@ -414,64 +421,49 @@ static struct ast_config * realtime_multi_handler(const char *database,
  * same format as the other realtime functions.
  * 
  * \param database the database to use (ignored)
- * \param table		the table to use
+ * \param table the table to use
  * \param keyfield the column of the matching cell
- * \param entity	 the value of the matching cell
- * \param ap			 list of parameters and new values to update in the database
- * \return -1 if an error occurred, the number of affected rows otherwise
+ * \param entity the value of the matching cell
+ * \param ap list of parameters and new values to update in the database
+ * \retval the number of affected rows.
+ * \retval -1 if an error occurred.
  */
 static int realtime_update_handler(const char *database, const char *table,
 	const char *keyfield, const char *entity,
 	va_list ap);
 
 /*!
- * Asterisk callback function for the CLI status command.
+ * \brief Asterisk callback function for the CLI status command.
  * 
- * \param fd	 file descriptor provided by Asterisk to use with ast_cli()
+ * \param fd file descriptor provided by Asterisk to use with ast_cli()
  * \param argc number of arguments
  * \param argv arguments list
  * \return RESULT_SUCCESS
  */
 static int cli_status(int fd, int argc, char *argv[]);
 
-/*!
- * The SQLite database object.
- */
+/*! The SQLite database object. */
 static sqlite *db;
 
-/*!
- * Set to 1 if CDR support is enabled.
- */
+/*! Set to 1 if CDR support is enabled. */
 static int use_cdr;
 
-/*!
- * Set to 1 if the CDR callback function was registered.
- */
+/*! Set to 1 if the CDR callback function was registered. */
 static int cdr_registered;
 
-/*!
- * Set to 1 if the CLI status command callback function was registered.
- */
+/*! Set to 1 if the CLI status command callback function was registered. */
 static int cli_status_registered;
 
-/*!
- * The path of the database file.
- */
+/*! The path of the database file. */
 static char *dbfile;
 
-/*!
- * The name of the static configuration table.
- */
+/*! The name of the static configuration table. */
 static char *config_table;
 
-/*!
- * The name of the table used to store CDR entries.
- */
+/*! The name of the table used to store CDR entries. */
 static char *cdr_table;
 
-/*!
- * The number of registered virtual machines.
- */
+/*! The number of registered virtual machines. */
 static int vm_count;
 
 /*!
@@ -509,9 +501,7 @@ static struct ast_cli_entry cli_status_cmd =
  * Taken from Asterisk 1.2 cdr_sqlite.so.
  */
 
-/*!
- * SQL query format to create the CDR table if non existent.
- */
+/*! SQL query format to create the CDR table if non existent. */
 static char *sql_create_cdr_table =
 "CREATE TABLE '%q' ("
 "	id		INTEGER PRIMARY KEY,"
@@ -535,9 +525,7 @@ static char *sql_create_cdr_table =
 "	userfield	VARCHAR(255) NOT NULL DEFAULT ''"
 ");";
 
-/*!
- * SQL query format to insert a CDR entry.
- */
+/*! SQL query format to insert a CDR entry. */
 static char *sql_add_cdr_entry =
 "INSERT INTO '%q' ("
 "			 clid,"
@@ -583,7 +571,7 @@ static char *sql_add_cdr_entry =
  * SQL query format to fetch the static configuration of a file.
  * Rows must be sorted by category.
  * 
- * @see add_cfg_entry()
+ * \see add_cfg_entry()
  */
 static char *sql_get_config_table =
 "SELECT *"

res/res_convert.c

@@ -56,7 +56,14 @@ static int split_ext(char *filename, char **name, char **ext)
 	return 0;
 }
 
-/*! \brief Convert a file from one format to another */
+/*! 
+ * \brief Convert a file from one format to another 
+ * \param fd file descriptor
+ * \param argc no arguements
+ * \param argv list of arguements
+ * \retval RESULT_SUCCESS on success.
+ * \retval RESULT_SHOWUSAGE on failure.
+*/
 static int cli_audio_convert(int fd, int argc, char *argv[])
 {
 	int ret = RESULT_FAILURE;

res/res_crypto.c

@@ -84,21 +84,21 @@ AST_MUTEX_DEFINE_STATIC(keylock);
 #define KEY_NEEDS_PASSCODE (1 << 16)
 
 struct ast_key {
-	/* Name of entity */
+	/*! Name of entity */
 	char name[80];
-	/* File name */
+	/*! File name */
 	char fn[256];
-	/* Key type (AST_KEY_PUB or AST_KEY_PRIV, along with flags from above) */
+	/*! Key type (AST_KEY_PUB or AST_KEY_PRIV, along with flags from above) */
 	int ktype;
-	/* RSA structure (if successfully loaded) */
+	/*! RSA structure (if successfully loaded) */
 	RSA *rsa;
-	/* Whether we should be deleted */
+	/*! Whether we should be deleted */
 	int delme;
-	/* FD for input (or -1 if no input allowed, or -2 if we needed input) */
+	/*! FD for input (or -1 if no input allowed, or -2 if we needed input) */
 	int infd;
-	/* FD for output */
+	/*! FD for output */
 	int outfd;
-	/* Last MD5 Digest */
+	/*! Last MD5 Digest */
 	unsigned char digest[16];
 	struct ast_key *next;
 };
@@ -112,6 +112,16 @@ static int fdprint(int fd, char *s)
         return write(fd, s, strlen(s) + 1);
 }
 #endif
+
+
+/*!
+ * \brief setting of priv key
+ * \param buf
+ * \param size
+ * \param rwflag
+ * \param userdata
+ * \return length of string,-1 on failure
+*/
 static int pw_cb(char *buf, int size, int rwflag, void *userdata)
 {
 	struct ast_key *key = (struct ast_key *)userdata;
@@ -137,6 +147,10 @@ static int pw_cb(char *buf, int size, int rwflag, void *userdata)
 	return -1;
 }
 
+/*!
+ * \brief return the ast_key structure for name
+ * \see ast_key_get
+*/
 static struct ast_key *__ast_key_get(const char *kname, int ktype)
 {
 	struct ast_key *key;
@@ -152,6 +166,16 @@ static struct ast_key *__ast_key_get(const char *kname, int ktype)
 	return key;
 }
 
+/*!
+ * \brief load RSA key from file
+ * \param dir directory string
+ * \param fname name of file
+ * \param ifd incoming file descriptor
+ * \param ofd outgoing file descriptor
+ * \param not2
+ * \retval key on success.
+ * \retval NULL on failure.
+*/
 static struct ast_key *try_load_key (char *dir, char *fname, int ifd, int ofd, int *not2)
 {
 	int ktype = 0;
@@ -318,6 +342,10 @@ static char *binary(int y, int len)
 
 #endif
 
+/*!
+ * \brief signs outgoing message with public key
+ * \see ast_sign_bin
+*/
 static int __ast_sign_bin(struct ast_key *key, const char *msg, int msglen, unsigned char *dsig)
 {
 	unsigned char digest[20];
@@ -349,6 +377,10 @@ static int __ast_sign_bin(struct ast_key *key, const char *msg, int msglen, unsi
 	
 }
 
+/*!
+ * \brief decrypt a message
+ * \see ast_decrypt_bin
+*/
 static int __ast_decrypt_bin(unsigned char *dst, const unsigned char *src, int srclen, struct ast_key *key)
 {
 	int res;
@@ -375,6 +407,10 @@ static int __ast_decrypt_bin(unsigned char *dst, const unsigned char *src, int s
 	return pos;
 }
 
+/*!
+ * \brief encrypt a message
+ * \see ast_encrypt_bin
+*/
 static int __ast_encrypt_bin(unsigned char *dst, const unsigned char *src, int srclen, struct ast_key *key)
 {
 	int res;
@@ -403,6 +439,10 @@ static int __ast_encrypt_bin(unsigned char *dst, const unsigned char *src, int s
 	return pos;
 }
 
+/*!
+ * \brief wrapper for __ast_sign_bin then base64 encode it
+ * \see ast_sign
+*/
 static int __ast_sign(struct ast_key *key, char *msg, char *sig)
 {
 	unsigned char dsig[128];
@@ -416,6 +456,10 @@ static int __ast_sign(struct ast_key *key, char *msg, char *sig)
 	
 }
 
+/*!
+ * \brief check signature of a message
+ * \see ast_check_signature_bin
+*/
 static int __ast_check_signature_bin(struct ast_key *key, const char *msg, int msglen, const unsigned char *dsig)
 {
 	unsigned char digest[20];
@@ -442,6 +486,10 @@ static int __ast_check_signature_bin(struct ast_key *key, const char *msg, int m
 	return 0;
 }
 
+/*!
+ * \brief base64 decode then sent to __ast_check_signature_bin
+ * \see ast_check_signature
+*/
 static int __ast_check_signature(struct ast_key *key, const char *msg, const char *sig)
 {
 	unsigned char dsig[128];
@@ -457,6 +505,12 @@ static int __ast_check_signature(struct ast_key *key, const char *msg, const cha
 	return res;
 }
 
+/*!
+ * \brief refresh RSA keys from file
+ * \param ifd file descriptor
+ * \param ofd file descriptor
+ * \return void
+*/
 static void crypto_load(int ifd, int ofd)
 {
 	struct ast_key *key, *nkey, *last;
@@ -512,6 +566,13 @@ static void md52sum(char *sum, unsigned char *md5)
 		sum += sprintf(sum, "%02x", *(md5++));
 }
 
+/*! 
+ * \brief show the list of RSA keys 
+ * \param fd file descriptor
+ * \param argc no of arguements
+ * \param argv list of arguements
+ * \return RESULT_SUCCESS
+*/
 static int show_keys(int fd, int argc, char *argv[])
 {
 	struct ast_key *key;
@@ -535,6 +596,13 @@ static int show_keys(int fd, int argc, char *argv[])
 	return RESULT_SUCCESS;
 }
 
+/*! 
+ * \brief initialize all RSA keys  
+ * \param fd file descriptor
+ * \param argc no of arguements
+ * \param argv list of arguements
+ * \return RESULT_SUCCESS
+*/
 static int init_keys(int fd, int argc, char *argv[])
 {
 	struct ast_key *key;
@@ -573,6 +641,7 @@ static struct ast_cli_entry cli_crypto[] = {
 	init_keys_usage },
 };
 
+/*! \brief initialise the res_crypto module */
 static int crypto_init(void)
 {
 	SSL_library_init();

res/res_indications.c

@@ -80,8 +80,11 @@ char *playtones_desc=
  * Implementation of functions provided by this module
  */
 
-/*
- * ADD INDICATION command stuff
+/*!
+ * \brief Add a country to indication
+ * \param fd file descriptor of CLI
+ * \param argc no of args
+ * \param argv arguements
  */
 static int handle_add_indication(int fd, int argc, char *argv[])
 {
@@ -114,8 +117,11 @@ static int handle_add_indication(int fd, int argc, char *argv[])
 	return 0;
 }
 
-/*
- * REMOVE INDICATION command stuff
+/*!
+ * \brief Remove a country from indication
+ * \param fd file descriptor of CLI
+ * \param argc no of args
+ * \param argv arguements
  */
 static int handle_remove_indication(int fd, int argc, char *argv[])
 {
@@ -143,8 +149,11 @@ static int handle_remove_indication(int fd, int argc, char *argv[])
 	return 0;
 }
 
-/*
- * SHOW INDICATIONS command stuff
+/*!
+ * \brief Show the current indications
+ * \param fd file descriptor of CLI
+ * \param argc no of args
+ * \param argv arguements
  */
 static int handle_show_indications(int fd, int argc, char *argv[])
 {
@@ -191,8 +200,10 @@ static int handle_show_indications(int fd, int argc, char *argv[])
 	return -1;
 }
 
-/*
- * Playtones command stuff
+/*!
+ * \brief play tone for indication country
+ * \param chan ast_channel to play the sounds back to
+ * \param data contains tone to play
  */
 static int handle_playtones(struct ast_channel *chan, void *data)
 {
@@ -213,8 +224,10 @@ static int handle_playtones(struct ast_channel *chan, void *data)
 	return res;
 }
 
-/*
- * StopPlaylist command stuff
+/*!
+ * \brief Stop tones playing
+ * \param chan 
+ * \param data 
  */
 static int handle_stopplaytones(struct ast_channel *chan, void *data)
 {
@@ -222,9 +235,7 @@ static int handle_stopplaytones(struct ast_channel *chan, void *data)
 	return 0;
 }
 
-/*
- * Load module stuff
- */
+/*! \brief load indications module */
 static int ind_load_module(void)
 {
 	struct ast_config *cfg;
@@ -342,9 +353,7 @@ out:			v = v->next;
 	return 0;
 }
 
-/*
- * CLI entries for commands provided by this module
- */
+/*! \brief CLI entries for commands provided by this module */
 static struct ast_cli_entry cli_indications[] = {
 	{ { "indication", "add", NULL },
 	handle_add_indication, "Add the given indication to the country",
@@ -359,9 +368,7 @@ static struct ast_cli_entry cli_indications[] = {
 	help_show_indications },
 };
 
-/*
- * Standard module functions ...
- */
+/*! \brief Unload indicators module */
 static int unload_module(void)
 {
 	/* remove the registed indications... */
@@ -375,6 +382,7 @@ static int unload_module(void)
 }
 
 
+/*! \brief Load indications module */
 static int load_module(void)
 {
 	if (ind_load_module())
@@ -386,6 +394,7 @@ static int load_module(void)
 	return 0;
 }
 
+/*! \brief Reload indications module */
 static int reload(void)
 {
 	/* remove the registed indications... */

res/res_monitor.c

@@ -115,6 +115,13 @@ static char *unpausemonitor_descrip = "UnpauseMonitor\n"
 	"Unpauses monitoring of a channel on which monitoring had\n"
 	"previously been paused with PauseMonitor.\n";
 
+/*! 
+ * \brief Change state of monitored channel 
+ * \param chan 
+ * \param state monitor state
+ * \retval 0 on success.
+ * \retval -1 on failure.
+*/
 static int ast_monitor_set_state(struct ast_channel *chan, int state)
 {
 	LOCK_IF_NEEDED(chan, 1);
@@ -133,7 +140,10 @@ static int ast_monitor_set_state(struct ast_channel *chan, int state)
  * \param fname_base filename base to record to
  * \param need_lock whether to lock the channel mutex
  * \param stream_action whether to record the input and/or output streams.  X_REC_IN | X_REC_OUT is most often used
- * \returns 0 on success, -1 on failure
+ * Creates the file to record, if no format is specified it assumes WAV
+ * It also sets channel variable __MONITORED=yes
+ * \retval 0 on success
+ * \retval -1 on failure
  */
 int ast_monitor_start(	struct ast_channel *chan, const char *format_spec,
 		const char *fname_base, int need_lock, int stream_action)
@@ -241,7 +251,9 @@ int ast_monitor_start(	struct ast_channel *chan, const char *format_spec,
 	return res;
 }
 
-/*
+/*!
+ * \brief Get audio format.
+ * \param format recording format.
  * The file format extensions that Asterisk uses are not all the same as that
  * which soxmix expects.  This function ensures that the format used as the
  * extension on the filename is something soxmix will understand.
@@ -258,7 +270,13 @@ static const char *get_soxmix_format(const char *format)
 	return res;
 }
 
-/* Stop monitoring a channel */
+/*! 
+ * \brief Stop monitoring channel 
+ * \param chan 
+ * \param need_lock
+ * Stop the recording, close any open streams, mix in/out channels if required
+ * \return Always 0
+*/
 int ast_monitor_stop(struct ast_channel *chan, int need_lock)
 {
 	int delfiles = 0;
@@ -339,29 +357,38 @@ int ast_monitor_stop(struct ast_channel *chan, int need_lock)
 }
 
 
-/* Pause monitoring of a channel */
+/*! \brief Pause monitoring of channel */
 int ast_monitor_pause(struct ast_channel *chan)
 {
 	return ast_monitor_set_state(chan, AST_MONITOR_PAUSED);
 }
 
-/* Unpause monitoring of a channel */
+/*! \brief Unpause monitoring of channel */
 int ast_monitor_unpause(struct ast_channel *chan)
 {
 	return ast_monitor_set_state(chan, AST_MONITOR_RUNNING);
 }
 
+/*! \brief Wrapper for ast_monitor_pause */
 static int pause_monitor_exec(struct ast_channel *chan, void *data)
 {
 	return ast_monitor_pause(chan);
 }
 
+/*! \brief Wrapper for ast_monitor_unpause */
 static int unpause_monitor_exec(struct ast_channel *chan, void *data)
 {
 	return ast_monitor_unpause(chan);
 }
 
-/* Change monitoring filename of a channel */
+/*! 
+ * \brief Change monitored filename of channel 
+ * \param chan
+ * \param fname_base new filename
+ * \param need_lock
+ * \retval 0 on success.
+ * \retval -1 on failure.
+*/
 int ast_monitor_change_fname(struct ast_channel *chan, const char *fname_base, int need_lock)
 {
 	if (ast_strlen_zero(fname_base)) {
@@ -390,6 +417,14 @@ int ast_monitor_change_fname(struct ast_channel *chan, const char *fname_base, i
 	return 0;
 }
 
+ 
+/*!
+ * \brief Start monitor
+ * \param chan
+ * \param data arguements passed  fname|options
+ * \retval 0 on success.
+ * \retval -1 on failure.
+*/
 static int start_monitor_exec(struct ast_channel *chan, void *data)
 {
 	char *arg = NULL;
@@ -470,11 +505,13 @@ static int start_monitor_exec(struct ast_channel *chan, void *data)
 	return res;
 }
 
+/*! \brief Wrapper function \see ast_monitor_stop */
 static int stop_monitor_exec(struct ast_channel *chan, void *data)
 {
 	return ast_monitor_stop(chan, 1);
 }
 
+/*! \brief Wrapper function \see ast_monitor_change_fname */
 static int change_monitor_exec(struct ast_channel *chan, void *data)
 {
 	return ast_monitor_change_fname(chan, (const char*)data, 1);
@@ -494,6 +531,7 @@ static char start_monitor_action_help[] =
 "                the input and output channels together after the\n"
 "                recording is finished.\n";
 
+/*! \brief Start monitoring a channel by manager connection */
 static int start_monitor_action(struct mansession *s, const struct message *m)
 {
 	struct ast_channel *c = NULL;
@@ -547,6 +585,7 @@ static char stop_monitor_action_help[] =
 "  started 'Monitor' action.  The only parameter is 'Channel', the name\n"
 "  of the channel monitored.\n";
 
+/*! \brief Stop monitoring a channel by manager connection */
 static int stop_monitor_action(struct mansession *s, const struct message *m)
 {
 	struct ast_channel *c = NULL;
@@ -579,6 +618,7 @@ static char change_monitor_action_help[] =
 "  File        - Required.  Is the new name of the file created in the\n"
 "                monitor spool directory.\n";
 
+/*! \brief Change filename of a monitored channel by manager connection */
 static int change_monitor_action(struct mansession *s, const struct message *m)
 {
 	struct ast_channel *c = NULL;

res/res_snmp.c

@@ -40,6 +40,10 @@ int res_snmp_enabled;
 
 static pthread_t thread = AST_PTHREADT_NULL;
 
+/*!
+ * \brief Load res_snmp.conf config file
+ * \return 1 on load, 0 file does not exist
+*/
 static int load_config(void)
 {
 	struct ast_variable *var;