issue #5605

git-svn-id: http://svn.digium.com/svn/asterisk/trunk@6979 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 52 insertions, 43 deletions

diff --git a/include/asterisk/app.h b/include/asterisk/app.h
index b7d0e2fa7..3c9c49e48 100755
--- a/include/asterisk/app.h
+++ b/include/asterisk/app.h
@@ -29,46 +29,46 @@ extern "C" {
 
 /* IVR stuff */
 
-/* Callback function for IVR, returns 0 on completion, -1 on hangup or digit if
-   interrupted */
+/*! \brief Callback function for IVR
+    \return returns 0 on completion, -1 on hangup or digit if interrupted 
+  */
 typedef int (*ast_ivr_callback)(struct ast_channel *chan, char *option, void *cbdata);
 
 typedef enum {
-	AST_ACTION_UPONE,		/* adata is unused */
-	AST_ACTION_EXIT,		/* adata is the return value for ast_ivr_menu_run if channel was not hungup */
-	AST_ACTION_CALLBACK,	/* adata is an ast_ivr_callback */
-	AST_ACTION_PLAYBACK,	/* adata is file to play */
-	AST_ACTION_BACKGROUND,	/* adata is file to play */
-	AST_ACTION_PLAYLIST,	/* adata is list of files, separated by ; to play */
-	AST_ACTION_MENU,		/* adata is a pointer to an ast_ivr_menu */
-	AST_ACTION_REPEAT,		/* adata is max # of repeats, cast to a pointer */
-	AST_ACTION_RESTART,		/* adata is like repeat, but resets repeats to 0 */
-	AST_ACTION_TRANSFER,	/* adata is a string with exten[@context] */
-	AST_ACTION_WAITOPTION,	/* adata is a timeout, or 0 for defaults */
-	AST_ACTION_NOOP,		/* adata is unused */
-	AST_ACTION_BACKLIST,	/* adata is list of files separated by ; allows interruption */
+	AST_ACTION_UPONE,	/*!< adata is unused */
+	AST_ACTION_EXIT,	/*!< adata is the return value for ast_ivr_menu_run if channel was not hungup */
+	AST_ACTION_CALLBACK,	/*!< adata is an ast_ivr_callback */
+	AST_ACTION_PLAYBACK,	/*!< adata is file to play */
+	AST_ACTION_BACKGROUND,	/*!< adata is file to play */
+	AST_ACTION_PLAYLIST,	/*!< adata is list of files, separated by ; to play */
+	AST_ACTION_MENU,	/*!< adata is a pointer to an ast_ivr_menu */
+	AST_ACTION_REPEAT,	/*!< adata is max # of repeats, cast to a pointer */
+	AST_ACTION_RESTART,	/*!< adata is like repeat, but resets repeats to 0 */
+	AST_ACTION_TRANSFER,	/*!< adata is a string with exten[@context] */
+	AST_ACTION_WAITOPTION,	/*!< adata is a timeout, or 0 for defaults */
+	AST_ACTION_NOOP,	/*!< adata is unused */
+	AST_ACTION_BACKLIST,	/*!< adata is list of files separated by ; allows interruption */
 } ast_ivr_action;
 
+/*! 
+    Special "options" are: 
+   \arg "s" - "start here (one time greeting)"
+   \arg "g" - "greeting/instructions"
+   \arg "t" - "timeout"
+   \arg "h" - "hangup"
+   \arg "i" - "invalid selection"
+
+*/
 struct ast_ivr_option {
 	char *option;
 	ast_ivr_action action;
 	void *adata;	
 };
 
-/* 
-    Special "options" are: 
-   "s" - "start here (one time greeting)"
-   "g" - "greeting/instructions"
-   "t" - "timeout"
-   "h" - "hangup"
-   "i" - "invalid selection"
-
-*/
-
 struct ast_ivr_menu {
-	char *title;		/* Title of menu */
-	unsigned int flags;	/* Flags */
-	struct ast_ivr_option *options;	/* All options */
+	char *title;		/*!< Title of menu */
+	unsigned int flags;	/*!< Flags */
+	struct ast_ivr_option *options;	/*!< All options */
 };
 
 #define AST_IVR_FLAG_AUTORESTART (1 << 0)
@@ -78,11 +78,11 @@ struct ast_ivr_menu {
 	static struct ast_ivr_menu holder = { title, flags, __options_##holder }
 	
 
-/*! Runs an IVR menu, returns 0 on successful completion, -1 on hangup, or -2 on user error in menu */
+/*!	\brief Runs an IVR menu 
+	\return returns 0 on successful completion, -1 on hangup, or -2 on user error in menu */
 extern int ast_ivr_menu_run(struct ast_channel *c, struct ast_ivr_menu *menu, void *cbdata);
 
-/*! Plays a stream and gets DTMF data from a channel */
-/*!
+/*! \brief Plays a stream and gets DTMF data from a channel 
  * \param c Which channel one is interacting with
  * \param prompt File to pass to ast_streamfile (the one that you wish to play)
  * \param s The location where the DTMF data will be stored
@@ -96,7 +96,7 @@ extern int ast_ivr_menu_run(struct ast_channel *c, struct ast_ivr_menu *menu, vo
  */
 extern int ast_app_getdata(struct ast_channel *c, char *prompt, char *s, int maxlen, int timeout);
 
-/* Full version with audiofd and controlfd.  NOTE: returns '2' on ctrlfd available, not '1' like other full functions */
+/*! \brief Full version with audiofd and controlfd.  NOTE: returns '2' on ctrlfd available, not '1' like other full functions */
 extern int ast_app_getdata_full(struct ast_channel *c, char *prompt, char *s, int maxlen, int timeout, int audiofd, int ctrlfd);
 
 /*! Record voice (after playing prompt if specified), waiting for silence (in ms) up to a given timeout (in s) or '#' */
@@ -113,7 +113,9 @@ int ast_app_has_voicemail(const char *mailbox, const char *folder);
 /*! Determine number of new/old messages in a mailbox */
 int ast_app_messagecount(const char *mailbox, int *newmsgs, int *oldmsgs);
 
-/*! Safely spawn an external program while closingn file descriptors */
+/*! Safely spawn an external program while closing file descriptors 
+	\note This replaces the \b system call in all Asterisk modules
+*/
 extern int ast_safe_system(const char *s);
 
 /*! Send DTMF to chan (optionally entertain peer)   */
@@ -128,13 +130,18 @@ int ast_control_streamfile(struct ast_channel *chan, const char *file, const cha
 /*! Play a stream and wait for a digit, returning the digit that was pressed */
 int ast_play_and_wait(struct ast_channel *chan, const char *fn);
 
-/*! Record a file for a max amount of time (in seconds), in a given list of formats separated by '|', outputting the duration of the recording, and with a maximum */
-/*   permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults. 
+/*! Record a file for a max amount of time (in seconds), in a given list of formats separated by '|', outputting the duration of the recording, and with a maximum 
+ \n
+ permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults. 
      calls ast_unlock_path() on 'path' if passed */
 int ast_play_and_record(struct ast_channel *chan, const char *playfile, const char *recordfile, int maxtime_sec, const char *fmt, int *duration, int silencethreshold, int maxsilence_ms, const char *path);
 
-/*! Record a message and prepend the message to the given record file after playing the optional playfile (or a beep), storing the duration in 'duration' and with a maximum */
-/*   permitted silence time in milliseconds of 'maxsilence' under 'silencethreshold' or use '-1' for either or both parameters for defaults. */
+/*! Record a message and prepend the message to the given record file after 
+    playing the optional playfile (or a beep), storing the duration in 
+    'duration' and with a maximum  
+\n
+  permitted silence time in milliseconds of 'maxsilence' under 
+  'silencethreshold' or use '-1' for either or both parameters for defaults. */
 int ast_play_and_prepend(struct ast_channel *chan, char *playfile, char *recordfile, int maxtime_sec, char *fmt, int *duration, int beep, int silencethreshold, int maxsilence_ms);
 
 enum AST_LOCK_RESULT {
@@ -144,17 +151,17 @@ enum AST_LOCK_RESULT {
 	AST_LOCK_FAILURE = -3,
 };
 
-/*
+/*!
  * \brief Lock a filesystem path.
  * \param path the path to be locked
- * \return one of AST_LOCK_RESULT values
+ * \return one of \ref AST_LOCK_RESULT values
  */
 enum AST_LOCK_RESULT ast_lock_path(const char *path);
 
-/* Unlock a path */
+/*! Unlock a path */
 int ast_unlock_path(const char *path);
 
-/*Read a file into asterisk*/
+/*! Read a file into asterisk*/
 char *ast_read_textfile(const char *file);
 
 #define GROUP_CATEGORY_PREFIX "GROUP"
@@ -188,7 +195,7 @@ int ast_app_group_match_get_count(char *groupmatch, char *category);
   argc argument counter. The arguments must be declared using AST_APP_ARG,
   and they will all be character pointers (strings).
 
-  Note: The structure is <b>not</b> initialized, as the call to
+  \note The structure is <b>not</b> initialized, as the call to
   ast_separate_app_args() will perform that function before parsing
   the arguments.
  */
@@ -329,7 +336,9 @@ struct ast_app_option {
  */
 int ast_app_parse_options(const struct ast_app_option *options, struct ast_flags *flags, char **args, char *optstr);
 
-/*! Present a dialtone and collect a certain length extension.  Returns 1 on valid extension entered, -1 on hangup, or 0 on invalid extension. Note that if 'collect' holds digits already, new digits will be appended, so be sure it's initialized properly */
+/*! \brief Present a dialtone and collect a certain length extension. 
+    \return Returns 1 on valid extension entered, -1 on hangup, or 0 on invalid extension. 
+\note Note that if 'collect' holds digits already, new digits will be appended, so be sure it's initialized properly */
 int ast_app_dtget(struct ast_channel *chan, const char *context, char *collect, size_t size, int maxlen, int timeout);
 
 /*! Allow to record message and have a review option */