From 668a334f85dc1df89ff77511890b247196550983 Mon Sep 17 00:00:00 2001
From: Russell Bryant <russell@russellbryant.com>
Date: Tue, 7 Aug 2007 23:04:01 +0000
Subject: [PATCH] Add another big set of doxygen documentation improvements
 from snuffy. (closes issue #9892) (closes issue #10395)

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@78541 65c4cc65-6c06-0410-ace0-fbb531ad65f3
---
 include/asterisk/features.h |  44 ++++---
 main/pbx.c                  | 115 ++++++++++-------
 main/sha1.c                 | 136 +++++++------------
 pbx/pbx_spool.c             |  20 +--
 res/res_crypto.c            |  14 ++
 res/res_features.c          | 251 ++++++++++++++++++++++++++++++++----
 utils/smsq.c                |  22 +++-
 7 files changed, 404 insertions(+), 198 deletions(-)

diff --git a/include/asterisk/features.h b/include/asterisk/features.h
index 5e9d5f3d2d..7d52b6b03a 100644
--- a/include/asterisk/features.h
+++ b/include/asterisk/features.h
@@ -48,31 +48,37 @@ struct ast_call_feature {
 
 
 
-/*! \brief Park a call and read back parked location 
- *  \param chan the channel to actually be parked
-    \param host the channel which will have the parked location read to
-	Park the channel chan, and read back the parked location to the
-	host.  If the call is not picked up within a specified period of
-	time, then the call will return to the last step that it was in 
-	(in terms of exten, priority and context)
-	\param timeout is a timeout in milliseconds
-	\param extout is a parameter to an int that will hold the parked location, or NULL if you want
+/*!
+ * \brief Park a call and read back parked location 
+ * \param chan the channel to actually be parked
+ * \param host the channel which will have the parked location read to.
+ * \param timeout is a timeout in milliseconds
+ * \param extout is a parameter to an int that will hold the parked location, or NULL if you want
+ * Park the channel chan, and read back the parked location to the host. 
+ * If the call is not picked up within a specified period of time, 
+ * then the call will return to the last step that it was in 
+ * (in terms of exten, priority and context)
+ * \retval 0 on success.
+ * \retval -1 on failure.
 */
 int ast_park_call(struct ast_channel *chan, struct ast_channel *host, int timeout, int *extout);
 
-/*! \brief Park a call via a masqueraded channel
- *  \param rchan the real channel to be parked
-    \param host the channel to have the parking read to
-	Masquerade the channel rchan into a new, empty channel which is then
-	parked with ast_park_call
-	\param timeout is a timeout in milliseconds
-	\param extout is a parameter to an int that will hold the parked location, or NULL if you want
+/*! 
+ * \brief Park a call via a masqueraded channel
+ * \param rchan the real channel to be parked
+ * \param host the channel to have the parking read to.
+ * \param timeout is a timeout in milliseconds
+ * \param extout is a parameter to an int that will hold the parked location, or NULL if you want
+ * Masquerade the channel rchan into a new, empty channel which is then parked with ast_park_call
+ * \retval 0 on success.
+ * \retval -1 on failure.
 */
 int ast_masq_park_call(struct ast_channel *rchan, struct ast_channel *host, int timeout, int *extout);
 
-/*! \brief Determine system parking extension
- *  Returns the call parking extension for drivers that provide special
-    call parking help */
+/*! 
+ * \brief Determine system parking extension
+ * \returns the call parking extension for drivers that provide special call parking help 
+*/
 const char *ast_parking_ext(void);
 
 /*! \brief Determine system call pickup extension */
diff --git a/main/pbx.c b/main/pbx.c
index 419523db9f..7d1b554d08 100644
--- a/main/pbx.c
+++ b/main/pbx.c
@@ -775,21 +775,24 @@ static int ext_cmp(const char *a, const char *b)
  * third argument to extension_match_core.
  */
 enum ext_match_t {
-	E_MATCHMORE = 	0x00,	/* extension can match but only with more 'digits' */
-	E_CANMATCH =	0x01,	/* extension can match with or without more 'digits' */
-	E_MATCH =	0x02,	/* extension is an exact match */
-	E_MATCH_MASK =	0x03,	/* mask for the argument to extension_match_core() */
-	E_SPAWN =	0x12,	/* want to spawn an extension. Requires exact match */
-	E_FINDLABEL =	0x22	/* returns the priority for a given label. Requires exact match */
+	E_MATCHMORE = 	0x00,	/*!< extension can match but only with more 'digits' */
+	E_CANMATCH =	0x01,	/*!< extension can match with or without more 'digits' */
+	E_MATCH =	0x02,	/*!< extension is an exact match */
+	E_MATCH_MASK =	0x03,	/*!< mask for the argument to extension_match_core() */
+	E_SPAWN =	0x12,	/*!< want to spawn an extension. Requires exact match */
+	E_FINDLABEL =	0x22	/*!< returns the priority for a given label. Requires exact match */
 };
 
-/*
- * Internal function for ast_extension_{match|close}
- * return 0 on no-match, 1 on match, 2 on early match.
+/*!
+ * \internal
+ * \brief used ast_extension_{match|close}
  * mode is as follows:
  *	E_MATCH		success only on exact match
  *	E_MATCHMORE	success only on partial match (i.e. leftover digits in pattern)
  *	E_CANMATCH	either of the above.
+ * \retval 0 on no-match
+ * \retval 1 on match
+ * \retval 2 on early match.
  */
 
 static int _extension_match_core(const char *pattern, const char *data, enum ext_match_t mode)
@@ -944,7 +947,7 @@ static int matchcid(const char *cidpattern, const char *callerid)
 	return ast_extension_match(cidpattern, callerid);
 }
 
-/* request and result for pbx_find_extension */
+/*! request and result for pbx_find_extension */
 struct pbx_find_info {
 #if 0
 	const char *context;
@@ -1082,8 +1085,9 @@ static struct ast_exten *pbx_find_extension(struct ast_channel *chan,
 	return NULL;
 }
 
-/*! \brief extract offset:length from variable name.
- * Returns 1 if there is a offset:length part, which is
+/*! 
+ * \brief extract offset:length from variable name.
+ * \return 1 if there is a offset:length part, which is
  * trimmed off (values go into variables)
  */
 static int parse_variable_name(char *var, int *offset, int *length, int *isfunc)
@@ -1108,12 +1112,15 @@ static int parse_variable_name(char *var, int *offset, int *length, int *isfunc)
 	return 0;
 }
 
-/*! \brief takes a substring. It is ok to call with value == workspace.
- *
- * offset < 0 means start from the end of the string and set the beginning
+/*! 
+ *\brief takes a substring. It is ok to call with value == workspace.
+ * \param value
+ * \param offset < 0 means start from the end of the string and set the beginning
  *   to be that many characters back.
- * length is the length of the substring.  A value less than 0 means to leave
+ * \param length is the length of the substring, a value less than 0 means to leave
  * that many off the end.
+ * \param workspace
+ * \param workspace_len
  * Always return a copy in workspace.
  */
 static char *substring(const char *value, int offset, int length, char *workspace, size_t workspace_len)
@@ -1730,7 +1737,9 @@ static void pbx_substitute_variables(char *passdata, int datalen, struct ast_cha
  * E_FINDLABEL maps the label to a priority, and returns
  *	the priority on success, ... XXX
  * E_SPAWN, spawn an application,
- *	and return 0 on success, -1 on failure.
+ *	
+ * \retval 0 on success.
+ * \retval  -1 on failure.
  */
 static int pbx_extension_helper(struct ast_channel *c, struct ast_context *con,
 	const char *context, const char *exten, int priority,
@@ -1836,7 +1845,7 @@ static int pbx_extension_helper(struct ast_channel *c, struct ast_context *con,
 	}
 }
 
-/*! \brief  ast_hint_extension: Find hint for given extension in context */
+/*! \brief Find hint for given extension in context */
 static struct ast_exten *ast_hint_extension(struct ast_channel *c, const char *context, const char *exten)
 {
 	struct ast_exten *e;
@@ -1849,7 +1858,7 @@ static struct ast_exten *ast_hint_extension(struct ast_channel *c, const char *c
 	return e;
 }
 
-/*! \brief  ast_extensions_state2: Check state of extension by using hints */
+/*! \brief Check state of extension by using hints */
 static int ast_extension_state2(struct ast_exten *e)
 {
 	char hint[AST_MAX_EXTENSION];
@@ -1934,7 +1943,7 @@ static int ast_extension_state2(struct ast_exten *e)
 	return AST_EXTENSION_NOT_INUSE;
 }
 
-/*! \brief  ast_extension_state2str: Return extension_state as string */
+/*! \brief Return extension_state as string */
 const char *ast_extension_state2str(int extension_state)
 {
 	int i;
@@ -1946,7 +1955,7 @@ const char *ast_extension_state2str(int extension_state)
 	return "Unknown";
 }
 
-/*! \brief  ast_extension_state: Check extension state for an extension by using hint */
+/*! \brief Check extension state for an extension by using hint */
 int ast_extension_state(struct ast_channel *c, const char *context, const char *exten)
 {
 	struct ast_exten *e;
@@ -2042,7 +2051,7 @@ static void *device_state_thread(void *data)
 	return NULL;
 }
 
-/*! \brief  ast_extension_state_add: Add watcher for extension states */
+/*! \brief  Add watcher for extension states */
 int ast_extension_state_add(const char *context, const char *exten,
 			    ast_state_cb_type callback, void *data)
 {
@@ -2117,7 +2126,7 @@ int ast_extension_state_add(const char *context, const char *exten,
 	return cblist->id;
 }
 
-/*! \brief  ast_extension_state_del: Remove a watcher from the callback list */
+/*! \brief Remove a watcher from the callback list */
 int ast_extension_state_del(int id, ast_state_cb_type callback)
 {
 	struct ast_state_cb **p_cur = NULL;	/* address of pointer to us */
@@ -2154,7 +2163,7 @@ int ast_extension_state_del(int id, ast_state_cb_type callback)
 	return ret;
 }
 
-/*! \brief  ast_add_hint: Add hint to hint list, check initial extension state */
+/*! \brief Add hint to hint list, check initial extension state */
 static int ast_add_hint(struct ast_exten *e)
 {
 	struct ast_hint *hint;
@@ -2188,7 +2197,7 @@ static int ast_add_hint(struct ast_exten *e)
 	return 0;
 }
 
-/*! \brief  ast_change_hint: Change hint for an extension */
+/*! \brief Change hint for an extension */
 static int ast_change_hint(struct ast_exten *oe, struct ast_exten *ne)
 {
 	struct ast_hint *hint;
@@ -2207,7 +2216,7 @@ static int ast_change_hint(struct ast_exten *oe, struct ast_exten *ne)
 	return res;
 }
 
-/*! \brief  ast_remove_hint: Remove hint from extension */
+/*! \brief Remove hint from extension */
 static int ast_remove_hint(struct ast_exten *e)
 {
 	/* Cleanup the Notifys if hint is removed */
@@ -2242,7 +2251,7 @@ static int ast_remove_hint(struct ast_exten *e)
 }
 
 
-/*! \brief  ast_get_hint: Get hint for channel */
+/*! \brief Get hint for channel */
 int ast_get_hint(char *hint, int hintsize, char *name, int namesize, struct ast_channel *c, const char *context, const char *exten)
 {
 	struct ast_exten *e = ast_hint_extension(c, context, exten);
@@ -2290,7 +2299,7 @@ int ast_spawn_extension(struct ast_channel *c, const char *context, const char *
 	return pbx_extension_helper(c, NULL, context, exten, priority, NULL, callerid, E_SPAWN);
 }
 
-/* helper function to set extension and priority */
+/*! helper function to set extension and priority */
 static void set_ext_pri(struct ast_channel *c, const char *exten, int pri)
 {
 	ast_copy_string(c->exten, exten, sizeof(c->exten));
@@ -2298,9 +2307,10 @@ static void set_ext_pri(struct ast_channel *c, const char *exten, int pri)
 }
 
 /*!
- * \brief collect digits from the channel into the buffer,
- * return -1 on error, 0 on timeout or done.
- */
+ * \brief collect digits from the channel into the buffer.
+ * \retval 0 on timeout or done.
+ * \retval -1 on error.
+*/
 static int collect_digits(struct ast_channel *c, int waittime, char *buf, int buflen, int pos)
 {
 	int digit;
@@ -2531,7 +2541,11 @@ static int __ast_pbx_run(struct ast_channel *c)
 	return 0;
 }
 
-/* Returns 0 on success, non-zero if a configured limit (maxcalls, maxload, minmemfree) was reached */
+/*! 
+ * \brief Increase call count for channel
+ * \retval 0 on success
+ * \retval non-zero if a configured limit (maxcalls, maxload, minmemfree) was reached 
+*/
 static int increase_call_count(const struct ast_channel *c)
 {
 	int failed = 0;
@@ -2661,9 +2675,11 @@ int pbx_set_autofallthrough(int newval)
 	return oldval;
 }
 
-/* lookup for a context with a given name,
- * return with conlock held if found, NULL if not found
- */
+/*!
+ * \brief lookup for a context with a given name,
+ * \retval with conlock held if found.
+ * \retval NULL if not found.
+*/
 static struct ast_context *find_context_locked(const char *context)
 {
 	struct ast_context *c = NULL;
@@ -2678,11 +2694,12 @@ static struct ast_context *find_context_locked(const char *context)
 	return NULL;
 }
 
-/*
+/*!
+ * \brief Remove included contexts.
  * This function locks contexts list by &conlist, search for the right context
  * structure, leave context list locked and call ast_context_remove_include2
  * which removes include, unlock contexts list and return ...
- */
+*/
 int ast_context_remove_include(const char *context, const char *include, const char *registrar)
 {
 	int ret = -1;
@@ -2696,13 +2713,14 @@ int ast_context_remove_include(const char *context, const char *include, const c
 	return ret;
 }
 
-/*
+/*!
+ * \brief Locks context, remove included contexts, unlocks context.
  * When we call this function, &conlock lock must be locked, because when
  * we giving *con argument, some process can remove/change this context
  * and after that there can be segfault.
  *
- * This function locks given context, removes include, unlock context and
- * return.
+ * \retval 0 on success.
+ * \retval -1 on failure.
  */
 int ast_context_remove_include2(struct ast_context *con, const char *include, const char *registrar)
 {
@@ -4673,9 +4691,11 @@ static int ext_strncpy(char *dst, const char *src, int len)
 	return count;
 }
 
-/*! \brief add the extension in the priority chain.
- * returns 0 on success, -1 on failure
- */
+/*! 
+ * \brief add the extension in the priority chain.
+ * \retval 0 on success.
+ * \retval -1 on failure.
+*/
 static int add_pri(struct ast_context *con, struct ast_exten *tmp,
 	struct ast_exten *el, struct ast_exten *e, int replace)
 {
@@ -4953,11 +4973,10 @@ static void *async_wait(void *data)
 	return NULL;
 }
 
-/*! Function to post an empty cdr after a spool call fails.
- *
- *  This function posts an empty cdr for a failed spool call
- *
- */
+/*! 
+ * \brief Function to post an empty cdr after a spool call fails.
+ * \note This function posts an empty cdr for a failed spool call
+*/
 static int ast_pbx_outgoing_cdr_failed(void)
 {
 	/* allocate a channel */
diff --git a/main/sha1.c b/main/sha1.c
index 16ddd6aa39..2dba8a26f6 100644
--- a/main/sha1.c
+++ b/main/sha1.c
@@ -1,6 +1,6 @@
-/*
+/*! \file
  *
- * Based on the RFC 3174
+ * \brief Based on the RFC 3174
  * 
  * Full Copyright Statement
  *
@@ -63,9 +63,7 @@
 
 #include "asterisk/sha1.h"
 
-/*
- *  Define the SHA1 circular left shift macro
- */
+/*! Define the SHA1 circular left shift macro */
 #define SHA1CircularShift(bits,word) \
 		         (((word) << (bits)) | ((word) >> (32-(bits))))
 
@@ -73,20 +71,12 @@
 void SHA1PadMessage(SHA1Context *);
 void SHA1ProcessMessageBlock(SHA1Context *);
 
-/*
- *  SHA1Reset
- *
- *  Description:
- *	  This function will initialize the SHA1Context in preparation
- *	  for computing a new SHA1 message digest.
- *
- *  Parameters:
- *	  context: [in/out]
- *		   The context to reset.
- *
- *  Returns:
- *	  sha Error Code.
- *
+/*!
+ * \brief SHA1Reset
+ * \param context the context to be reset
+ * This function will initialize the SHA1Context in preparation
+ * for computing a new SHA1 message digest.
+ * \return sha Error Code.
  */
 int SHA1Reset(SHA1Context *context)
 {
@@ -110,24 +100,15 @@ int SHA1Reset(SHA1Context *context)
 	return shaSuccess;
 }
 
-/*
- *  SHA1Result
- *
- *  Description:
- *	  This function will return the 160-bit message digest into the
- *	  Message_Digest array  provided by the caller.
- *	  NOTE: The first octet of hash is stored in the 0th element,
- *		     the last octet of hash in the 19th element.
- *
- *  Parameters:
- *	  context: [in/out]
- *		   The context to use to calculate the SHA-1 hash.
- *	  Message_Digest: [out]
- *		   Where the digest is returned.
- *
- *  Returns:
- *	  sha Error Code.
- *
+/*!
+ * \brief SHA1Result
+ * \param context [in/out] The context to use to calculate the SHA-1 hash.
+ * \param Message_Digest [out] Where the digest is returned.
+ *  This function will return the 160-bit message digest into the
+ *  Message_Digest array  provided by the caller.
+ * \note The first octet of hash is stored in the 0th element, 
+ * 	the last octet of hash in the 19th element.
+ * \return sha Error Code.
  */
 int SHA1Result( SHA1Context *context,
 		         uint8_t Message_Digest[SHA1HashSize])
@@ -160,25 +141,15 @@ int SHA1Result( SHA1Context *context,
 	return shaSuccess;
 }
 
-/*
- *  SHA1Input
- *
- *  Description:
- *	  This function accepts an array of octets as the next portion
- *	  of the message.
- *
- *  Parameters:
- *	  context: [in/out]
- *		   The SHA context to update
- *	  message_array: [in]
- *		   An array of characters representing the next portion of
+/*!
+ *  \brief SHA1Input
+ * \param context [in/out] The SHA context to update
+ * \param message_array [in] An array of characters representing the next portion of
  *		   the message.
- *	  length: [in]
- *		   The length of the message in message_array
- *
- *  Returns:
- *	  sha Error Code.
- *
+ * \param length [in] The length of the message in message_array
+ *  This function accepts an array of octets as the next portion
+ *  of the message.
+ * \return sha Error Code.
  */
 int SHA1Input(SHA1Context *context, const uint8_t *message_array, unsigned length)
 {
@@ -221,25 +192,13 @@ int SHA1Input(SHA1Context *context, const uint8_t *message_array, unsigned lengt
 	return shaSuccess;
 }
 
-/*
- *  SHA1ProcessMessageBlock
- *
- *  Description:
- *	  This function will process the next 512 bits of the message
- *	  stored in the Message_Block array.
- *
- *  Parameters:
- *	  None.
- *
- *  Returns:
- *	  Nothing.
- *
- *  Comments:
- *	  Many of the variable names in this code, especially the
+/*!
+ * \brief Process the next 512 bits of the message stored in the Message_Block array.
+ * \param context [in/out] The SHA context to update
+ * \note  Many of the variable names in this code, especially the
  *	  single character names, were used because those were the
  *	  names used in the publication.
- *
- *
+ * \returns nothing.
  */
 void SHA1ProcessMessageBlock(SHA1Context *context)
 {
@@ -320,27 +279,20 @@ void SHA1ProcessMessageBlock(SHA1Context *context)
 }
 
 
-/*
- *  SHA1PadMessage
- *
- *  Description:
- *	  According to the standard, the message must be padded to an even
- *	  512 bits.  The first padding bit must be a '1'.  The last 64
- *	  bits represent the length of the original message.  All bits in
- *	  between should be 0.  This function will pad the message
- *	  according to those rules by filling the Message_Block array
- *	  accordingly.  It will also call the ProcessMessageBlock function
- *	  provided appropriately.  When it returns, it can be assumed that
- *	  the message digest has been computed.
- *
- *  Parameters:
- *	  context: [in/out]
- *		   The context to pad
- *	  ProcessMessageBlock: [in]
- *		   The appropriate SHA*ProcessMessageBlock function
- *  Returns:
- *	  Nothing.
+/*!
+ * \brief Pad message to be 512 bits.
+ * \param context [in/out]  The context to pad
+ * 
+ * According to the standard, the message must be padded to an even
+ *  512 bits.  The first padding bit must be a '1'.  The last 64
+ *  bits represent the length of the original message.  All bits in
+ *  between should be 0.  This function will pad the message
+ *  according to those rules by filling the Message_Block array
+ *  accordingly.  It will also call the ProcessMessageBlock function
+ *  provided appropriately.  When it returns, it can be assumed that
+ *  the message digest has been computed.
  *
+ * \returns nothing.
  */
 
 void SHA1PadMessage(SHA1Context *context)
diff --git a/pbx/pbx_spool.c b/pbx/pbx_spool.c
index e5ccddb474..6a037fdb86 100644
--- a/pbx/pbx_spool.c
+++ b/pbx/pbx_spool.c
@@ -68,18 +68,18 @@ static char qdonedir[255];
 
 struct outgoing {
 	char fn[256];
-	/* Current number of retries */
+	/*! Current number of retries */
 	int retries;
-	/* Maximum number of retries permitted */
+	/*! Maximum number of retries permitted */
 	int maxretries;
-	/* How long to wait between retries (in seconds) */
+	/*! How long to wait between retries (in seconds) */
 	int retrytime;
-	/* How long to wait for an answer */
+	/*! How long to wait for an answer */
 	int waittime;
-	/* PID which is currently calling */
+	/*! PID which is currently calling */
 	long callingpid;
 	
-	/* What to connect to outgoing */
+	/*! What to connect to outgoing */
 	char tech[256];
 	char dest[256];
 	
@@ -96,16 +96,16 @@ struct outgoing {
 	char cid_num[256];
 	char cid_name[256];
 
-	/* account code */
+	/*! account code */
 	char account[AST_MAX_ACCOUNT_CODE];
 
-	/* Variables and Functions */
+	/*! Variables and Functions */
 	struct ast_variable *vars;
 	
-	/* Maximum length of call */
+	/*! Maximum length of call */
 	int maxlen;
 
-	/* options */
+	/*! options */
 	struct ast_flags options;
 };
 
diff --git a/res/res_crypto.c b/res/res_crypto.c
index 65c5b768db..4ad6885c5a 100644
--- a/res/res_crypto.c
+++ b/res/res_crypto.c
@@ -94,6 +94,16 @@ struct ast_key {
 
 static AST_RWLIST_HEAD_STATIC(keys, ast_key);
 
+/*!
+ * \brief setting of priv key
+ * \param buf
+ * \param size
+ * \param rwflag
+ * \param userdata
+ * \return length of string,-1 on failure
+*/
+
+
 /*!
  * \brief setting of priv key
  * \param buf
@@ -279,6 +289,10 @@ static struct ast_key *try_load_key(char *dir, char *fname, int ifd, int ofd, in
 	return key;
 }
 
+/*!
+ * \brief signs outgoing message with public key
+ * \see ast_sign_bin
+*/
 /*!
  * \brief signs outgoing message with public key
  * \see ast_sign_bin
diff --git a/res/res_features.c b/res/res_features.c
index df08bb9711..1083948a52 100644
--- a/res/res_features.c
+++ b/res/res_features.c
@@ -197,7 +197,10 @@ struct ast_bridge_thread_obj
 
 
 
-/*! \brief store context, priority and extension */
+/*!
+ * \brief store context, extension and priority 
+ * \param chan, context, ext, pri
+*/
 static void set_c_e_p(struct ast_channel *chan, const char *context, const char *ext, int pri)
 {
 	ast_copy_string(chan->context, context, sizeof(chan->context));
@@ -205,6 +208,13 @@ static void set_c_e_p(struct ast_channel *chan, const char *context, const char
 	chan->priority = pri;
 }
 
+/*!
+ * \brief Check goto on transfer
+ * \param chan
+ * Check if channel has 'GOTO_ON_BLINDXFR' set, if not exit.
+ * When found make sure the types are compatible. Check if channel is valid
+ * if so start the new channel else hangup the call. 
+*/
 static void check_goto_on_transfer(struct ast_channel *chan) 
 {
 	struct ast_channel *xferchan;
@@ -243,7 +253,13 @@ static void check_goto_on_transfer(struct ast_channel *chan)
 
 static struct ast_channel *ast_feature_request_and_dial(struct ast_channel *caller, struct ast_channel *transferee, const char *type, int format, void *data, int timeout, int *outstate, const char *cid_num, const char *cid_name, int igncallerstate);
 
-
+/*!
+ * \brief bridge the call 
+ * \param data thread bridge 
+ * Set Last Data for respective channels, reset cdr for channels
+ * bridge call, check if we're going back to dialplan
+ * if not hangup both legs of the call
+*/
 static void *ast_bridge_call_thread(void *data) 
 {
 	struct ast_bridge_thread_obj *tobj = data;
@@ -290,6 +306,11 @@ static void *ast_bridge_call_thread(void *data)
 	return NULL;
 }
 
+/*!
+ * \brief create thread for the parked call
+ * \param data
+ * Create thread and attributes, call ast_bridge_call_thread
+*/
 static void ast_bridge_call_thread_launch(void *data) 
 {
 	pthread_t thread;
@@ -304,6 +325,14 @@ static void ast_bridge_call_thread_launch(void *data)
 	pthread_setschedparam(thread, SCHED_RR, &sched);
 }
 
+/*!
+ * \brief Announce call parking by ADSI
+ * \param chan
+ * \param parkingexten
+ * Create message to show for ADSI, display message.
+ * \retval 0 on success.
+ * \retval -1 on failure.
+*/
 static int adsi_announce_park(struct ast_channel *chan, char *parkingexten)
 {
 	int res;
@@ -349,9 +378,7 @@ static enum ast_device_state metermaidstate(const char *data)
 	return AST_DEVICE_INUSE;
 }
 
-/*! \brief Park a call 
- 	\note We put the user in the parking list, then wake up the parking thread to be sure it looks
-	after these channels too */
+/* Park a call */
 int ast_park_call(struct ast_channel *chan, struct ast_channel *peer, int timeout, int *extout)
 {
 	struct parkeduser *pu, *cur;
@@ -479,6 +506,7 @@ int ast_park_call(struct ast_channel *chan, struct ast_channel *peer, int timeou
 	return 0;
 }
 
+/* Park call via masquraded channel */
 int ast_masq_park_call(struct ast_channel *rchan, struct ast_channel *peer, int timeout, int *extout)
 {
 	struct ast_channel *chan;
@@ -519,9 +547,11 @@ int ast_masq_park_call(struct ast_channel *rchan, struct ast_channel *peer, int
 #define FEATURE_SENSE_CHAN	(1 << 0)
 #define FEATURE_SENSE_PEER	(1 << 1)
 
-/*! \brief
- * set caller and callee according to the direction
- */
+/*! 
+ * \brief set caller and callee according to the direction 
+ * \param caller, callee, peer, chan, sense
+ * Detect who triggered feature and set callee/caller variables accordingly
+*/
 static void set_peers(struct ast_channel **caller, struct ast_channel **callee,
 	struct ast_channel *peer, struct ast_channel *chan, int sense)
 {
@@ -534,7 +564,16 @@ static void set_peers(struct ast_channel **caller, struct ast_channel **callee,
 	}
 }
 
-/*! \brief support routing for one touch call parking */
+/*! 
+ * \brief support routing for one touch call parking
+ * \param chan channel parking call
+ * \param peer channel to be parked
+ * \param config unsed
+ * \param code unused
+ * \param sense feature options 
+ * Setup channel, set return exten,priority to 's,1'
+ * answer chan, sleep chan, park call
+*/
 static int builtin_parkcall(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, char *code, int sense)
 {
 	struct ast_channel *parker;
@@ -568,6 +607,18 @@ static int builtin_parkcall(struct ast_channel *chan, struct ast_channel *peer,
 
 }
 
+/*!
+ * \brief Monitor a channel by DTMF
+ * \param chan channel requesting monitor
+ * \param peer channel to be monitored
+ * \param config
+ * \param code
+ * \param sense
+ * Check monitor app enabled, setup channels, both caller/callee chans not null
+ * get TOUCH_MONITOR variable for filename if exists, exec monitor app.
+ * \retval FEATURE_RETURN_SUCCESS on success.
+ * \retval -1 on error.
+*/
 static int builtin_automonitor(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, char *code, int sense)
 {
 	char *caller_chan_id = NULL, *callee_chan_id = NULL, *args = NULL, *touch_filename = NULL;
@@ -663,7 +714,13 @@ static int finishup(struct ast_channel *chan)
         return ast_autoservice_stop(chan);
 }
 
-/*! \brief Find the context for the transfer */
+/*!
+ * \brief Find the context for the transfer
+ * \param transferer
+ * \param transferee
+ * Grab the TRANSFER_CONTEXT, if fails try grabbing macrocontext.
+ * \return a context string
+*/
 static const char *real_ctx(struct ast_channel *transferer, struct ast_channel *transferee)
 {
         const char *s = pbx_builtin_getvar_helper(transferer, "TRANSFER_CONTEXT");
@@ -676,6 +733,18 @@ static const char *real_ctx(struct ast_channel *transferer, struct ast_channel *
         return s;  
 }
 
+/*!
+ * \brief Blind transfer user to another extension
+ * \param chan channel initiated blind transfer
+ * \param peer channel to be transfered
+ * \param config
+ * \param code
+ * \param sense
+ * Place peer on hold, check if tranfered to parkinglot extension,
+ * otherwise check extension exists and transfer caller.
+ * \retval FEATURE_RETURN_SUCCESS.
+ * \retval -1 on failure.
+*/
 static int builtin_blindtransfer(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, char *code, int sense)
 {
 	struct ast_channel *transferer;
@@ -763,6 +832,13 @@ static int builtin_blindtransfer(struct ast_channel *chan, struct ast_channel *p
 	return FEATURE_RETURN_SUCCESS;
 }
 
+/*!
+ * \brief make channels compatible
+ * \param c
+ * \param newchan
+ * \retval 0 on success.
+ * \retval -1 on failure.
+*/
 static int check_compat(struct ast_channel *c, struct ast_channel *newchan)
 {
 	if (ast_channel_make_compatible(c, newchan) < 0) {
@@ -774,6 +850,18 @@ static int check_compat(struct ast_channel *c, struct ast_channel *newchan)
 	return 0;
 }
 
+/*!
+ * \brief Attended transfer
+ * \param chan
+ * \param peer
+ * \param config
+ * \param code
+ * \param sense
+ * Get extension to transfer to, if you cannot generate channel (or find extension) 
+ * return to host channel. After called channel answered wait for hangup of transferer,
+ * bridge call between transfer peer (taking them off hold) to attended transfer channel.
+ * \return -1 means what failure/success both?
+*/
 static int builtin_atxfer(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, char *code, int sense)
 {
 	struct ast_channel *transferer;
@@ -1034,7 +1122,12 @@ void ast_register_feature(struct ast_call_feature *feature)
 	ast_verb(2, "Registered Feature '%s'\n",feature->sname);
 }
 
-/*! \brief This function must be called while feature_groups is locked... */
+/*! 
+ * \brief Add new feature group
+ * \param fgname feature group name
+ * Add new feature group to the feature group list insert at head of list.
+ * \note This function MUST be called while feature_groups is locked.
+*/
 static struct feature_group* register_group(const char *fgname)
 {
 	struct feature_group *fg;
@@ -1061,8 +1154,14 @@ static struct feature_group* register_group(const char *fgname)
 	return fg;
 }
 
-/*! \brief This function must be called while feature_groups is locked... */
-
+/*! 
+ * \brief Add feature to group
+ * \param fg feature group
+ * \param exten
+ * \param feature feature to add
+ * Check fg and feature specified, add feature to list
+ * \note This function MUST be called while feature_groups is locked. 
+*/
 static void register_group_feature(struct feature_group *fg, const char *exten, struct ast_call_feature *feature) 
 {
 	struct feature_group_exten *fge;
@@ -1095,7 +1194,6 @@ static void register_group_feature(struct feature_group *fg, const char *exten,
 					feature->sname, fg->gname, exten);
 }
 
-/*! \brief unregister feature from feature_list */
 void ast_unregister_feature(struct ast_call_feature *feature)
 {
 	if (!feature)
@@ -1131,7 +1229,7 @@ static struct ast_call_feature *find_dynamic_feature(const char *name)
 	return tmp;
 }
 
-/*! \brief Remove all groups in the list */
+/*! \brief Remove all feature groups in the list */
 static void ast_unregister_groups(void)
 {
 	struct feature_group *fg;
@@ -1150,7 +1248,12 @@ static void ast_unregister_groups(void)
 	AST_RWLIST_UNLOCK(&feature_groups);
 }
 
-/*! \brief Find a group by name */
+/*! 
+ * \brief Find a group by name 
+ * \param name feature name
+ * \retval feature group on success.
+ * \retval NULL on failure.
+*/
 static struct feature_group *find_group(const char *name) {
 	struct feature_group *fg = NULL;
 
@@ -1162,6 +1265,12 @@ static struct feature_group *find_group(const char *name) {
 	return fg;
 }
 
+/*! 
+ * \brief Find a feature extension 
+ * \param fg, code
+ * \retval feature group extension on success.
+ * \retval NULL on failure.
+*/
 static struct feature_group_exten *find_group_exten(struct feature_group *fg, const char *code) {
 	struct feature_group_exten *fge = NULL;
 
@@ -1183,7 +1292,6 @@ void ast_unlock_call_features(void)
 	ast_rwlock_unlock(&features_lock);
 }
 
-/*! \brief find a call feature by name */
 struct ast_call_feature *ast_find_call_feature(const char *name)
 {
 	int x;
@@ -1194,7 +1302,14 @@ struct ast_call_feature *ast_find_call_feature(const char *name)
 	return NULL;
 }
 
-/*! \brief exec an app by feature */
+/*!
+ * \brief exec an app by feature 
+ * \param chan,peer,config,code,sense
+ * Find a feature, determine which channel activated
+ * \retval FEATURE_RETURN_PBX_KEEPALIVE,FEATURE_RETURN_NO_HANGUP_PEER
+ * \retval -1 error.
+ * \retval -2 when an application cannot be found.
+*/
 static int feature_exec_app(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, char *code, int sense)
 {
 	struct ast_app *app;
@@ -1291,6 +1406,13 @@ static int remap_feature(const char *name, const char *value)
 	return res;
 }
 
+/*!
+ * \brief Check the dynamic features
+ * \param chan,peer,config,code,sense
+ * Lock features list, browse for code, unlock list
+ * \retval res on success.
+ * \retval -1 on failure.
+*/
 static int ast_feature_interpret(struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, char *code, int sense)
 {
 	int x;
@@ -1405,7 +1527,15 @@ static void set_config_flags(struct ast_channel *chan, struct ast_channel *peer,
 	}
 }
 
-/*! \todo XXX Check - this is very similar to the code in channel.c */
+/*! 
+ * \brief
+ * \param caller,transferee,type,format,data,timeout,outstate,cid_num,cid_name,igncallerstate
+ * Request channel, set channel variables, initiate call,check if they want to disconnect
+ * go into loop, check if timeout has elapsed, check if person to be transfered hung up,
+ * check for answer break loop, set cdr return channel.
+ * \todo XXX Check - this is very similar to the code in channel.c 
+ * \return always a channel
+*/
 static struct ast_channel *ast_feature_request_and_dial(struct ast_channel *caller, struct ast_channel *transferee, const char *type, int format, void *data, int timeout, int *outstate, const char *cid_num, const char *cid_name, int igncallerstate)
 {
 	int state = 0;
@@ -1587,6 +1717,14 @@ static struct ast_channel *ast_feature_request_and_dial(struct ast_channel *call
 	return chan;
 }
 
+/*!
+ * \brief bridge the call and set CDR
+ * \param chan,peer,config
+ * Set start time, check for two channels,check if monitor on
+ * check for feature activation, create new CDR
+ * \retval res on success.
+ * \retval -1 on failure to bridge.
+*/
 int ast_bridge_call(struct ast_channel *chan,struct ast_channel *peer,struct ast_bridge_config *config)
 {
 	/* Copy voice back and forth between the two channels.  Give the peer
@@ -1878,7 +2016,13 @@ static void post_manager_event(const char *s, struct parkeduser *pu)
 		);
 }
 
-/*! \brief Take care of parked calls and unpark them if needed */
+/*! 
+ * \brief Take care of parked calls and unpark them if needed 
+ * \param ignore unused var
+ * Start inf loop, lock parking lot, check if any parked channels have gone above timeout
+ * if so, remove channel from parking lot and return it to the extension that parked it.
+ * Check if parked channel decided to hangup, wait until next FD via select().
+*/
 static void *do_parking_thread(void *ignore)
 {
 	char parkingslot[AST_MAX_EXTENSION];
@@ -2240,6 +2384,13 @@ static char mandescr_bridge[] =
 "        Tone: (Yes|No) Play courtesy tone to Channel 2\n"
 "\n";
 
+/*!
+ * \brief Actual bridge
+ * \param chan
+ * \param tmpchan
+ * Stop hold music, lock both channels, masq channels,
+ * after bridge return channel to next priority.
+*/
 static void do_bridge_masquerade(struct ast_channel *chan, struct ast_channel *tmpchan)
 {
 	ast_moh_stop(chan);
@@ -2256,6 +2407,18 @@ static void do_bridge_masquerade(struct ast_channel *chan, struct ast_channel *t
 	ast_mutex_unlock(&chan->lock);
 }
 
+/*!
+ * \brief Bridge channels together
+ * \param s
+ * \param m
+ * Make sure valid channels were specified, 
+ * send errors if any of the channels could not be found/locked, answer channels if needed,
+ * create the placeholder channels and grab the other channels 
+ * make the channels compatible, send error if we fail doing so 
+ * setup the bridge thread object and start the bridge. 
+ * \retval 0 on success or on incorrect use.
+ * \retval 1 on failure to bridge channels.
+*/
 static int action_bridge(struct mansession *s, const struct message *m)
 {
 	const char *channela = astman_get_header(m, "Channel1");
@@ -2355,6 +2518,16 @@ static char showfeatures_help[] =
 "Usage: feature list\n"
 "       Lists currently configured features.\n";
 
+/*!
+ * \brief CLI command to list parked calls
+ * \param e 
+ * \param cmd
+ * \param a
+ * Check right usage, lock parking lot, display parked calls, unlock parking lot list.
+ * \retval CLI_SUCCESS on success.
+ * \retval CLI_SHOWUSAGE on incorrect number of arguements.
+ * \retval NULL when tab completion is used.
+*/
 static char *handle_parkedcalls(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
 {
 	struct parkeduser *cur;
@@ -2410,7 +2583,13 @@ static struct ast_cli_entry cli_features[] = {
 	NEW_CLI(handle_parkedcalls, "List currently parked calls", .deprecate_cmd = &cli_show_parkedcalls_deprecated),
 };
 
-/*! \brief Dump lot status */
+/*! 
+ * \brief Dump parking lot status
+ * \param s
+ * \param m
+ * Lock parking lot, iterate list and append parked calls status, unlock parking lot.
+ * \return Always RESULT_SUCCESS 
+*/
 static int manager_parking_status(struct mansession *s, const struct message *m)
 {
 	struct parkeduser *cur;
@@ -2458,6 +2637,13 @@ static char mandescr_park[] =
 "	*Channel2: Channel to announce park info to (and return to if timeout)\n"
 "	Timeout: Number of milliseconds to wait before callback.\n";  
 
+/*!
+ * \brief Create manager event for parked calls
+ * \param s
+ * \param m
+ * Get channels involved in park, create event.
+ * \return Always 0
+*/
 static int manager_park(struct mansession *s, const struct message *m)
 {
 	const char *channel = astman_get_header(m, "Channel");
@@ -2512,7 +2698,13 @@ static int manager_park(struct mansession *s, const struct message *m)
 	return 0;
 }
 
-
+/*!
+ * \brief Pickup a call
+ * \param chan channel that initiated pickup
+ * Walk list of channels, checking it is not itself, channel is pbx one,
+ * check that the callgroup for both channels are the same and the channel is ringing.
+ * Answer calling channel, flag channel as answered on queue, masq channels together.
+*/
 int ast_pickup_call(struct ast_channel *chan)
 {
 	struct ast_channel *cur = NULL;
@@ -2546,7 +2738,12 @@ int ast_pickup_call(struct ast_channel *chan)
 	return res;
 }
 
-/*! \brief Add parking hints for all defined parking lots */
+/*! 
+ * \brief Add parking hints for all defined parking lots 
+ * \param context
+ * \param start starting parkinglot number
+ * \param stop ending parkinglot number
+*/
 static void park_add_hints(char *context, int start, int stop)
 {
 	int numext;
@@ -2868,6 +3065,14 @@ AST_APP_OPTIONS(bridge_exec_options, BEGIN_OPTIONS
 	AST_APP_OPTION('p', BRIDGE_OPT_PLAYTONE)
 END_OPTIONS );
 
+/*!
+ * \brief Bridge channels
+ * \param chan
+ * \param data channel to bridge with
+ * Split data, check we aren't bridging with ourself, check valid channel,
+ * answer call if not already, check compatible channels, setup bridge config
+ * now bridge call, if transfered party hangs up return to PBX extension.
+*/
 static int bridge_exec(struct ast_channel *chan, void *data)
 {
 	struct ast_module_user *u;
diff --git a/utils/smsq.c b/utils/smsq.c
index 7439504fc6..f6baf0ad1d 100644
--- a/utils/smsq.c
+++ b/utils/smsq.c
@@ -38,9 +38,11 @@
 #endif
 
 
-/* reads next USC character from null terminated UTF-8 string and advanced pointer */
-/* for non valid UTF-8 sequences, returns character as is */
-/* Does not advance pointer for null termination */
+/*!
+ * \brief reads next USC character from null terminated UTF-8 string and advanced pointer
+ * for non valid UTF-8 sequences.
+ * \return character as is Does \b NOT advance pointer for null termination 
+*/
 static int utf8decode (unsigned char **pp)
 {
    unsigned char *p = *pp;
@@ -90,8 +92,13 @@ static int utf8decode (unsigned char **pp)
    return *p;                   /* not sensible */
 }
 
-/* check for any queued messages in specific queue (queue="" means any queue) */
-/* returns 0 if nothing queued, 1 if queued and outgoing set up OK, 2 of outgoing exists */
+/*! 
+ * \brief check for any queued messages in specific queue (queue="" means any queue)
+ * \param dir,queue,subaddress,channel,callerid,wait,delay,retries,concurrent
+ * \retval 0 if nothing queued
+ * \retval 1 if queued and outgoing set up OK
+ * \retval 2 of outgoing exists 
+*/
 static char txqcheck (char *dir, char *queue, char subaddress, char *channel, char *callerid, int wait, int delay, int retries, int concurrent)
 {
    char ogname[100],
@@ -186,7 +193,10 @@ static char txqcheck (char *dir, char *queue, char subaddress, char *channel, ch
    return 2;
 }
 
-/* Process received queue entries and run through a process, setting environment variables */
+/*! 
+ * \brief Process received queue entries
+ * Run through a process, setting environment variables
+*/
 static void rxqcheck (char *dir, char *queue, char *process)
 {
    char *p;
-- 
GitLab