Merge a bunch of doxygen updates to header files. This includes changes to

use the \retval tag for documenting return values, fixing various warnings
when generating the documentation, and various other things.
(closes issue #10203, snuffy)


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

1 files changed, 72 insertions, 77 deletions

diff --git a/include/asterisk/adsi.h b/include/asterisk/adsi.h
index 168bb9802..c4379dc88 100644
--- a/include/asterisk/adsi.h
+++ b/include/asterisk/adsi.h
@@ -117,13 +117,12 @@
 #define ADSI_DIR_FROM_LEFT (0)
 #define ADSI_DIR_FROM_RIGHT (1)
 
-/*! Perform Asterisk ADSI initialization (for channel drivers that want */
-/*    to support ADSI when the handset is first lifted) */
-/*!
+/*! Perform Asterisk ADSI initialization (for channel drivers that want 
+ *    to support ADSI when the handset is first lifted) 
  * \param chan Channel to initialize for ADSI (if supported)
  *
- * Returns 0 on success (or adsi unavailable) and -1 on hangup
- *
+ * \retval 0 on success (or adsi unavailable.
+ * \retval -1 on hangup.
  */
 extern int (*ast_adsi_channel_init)(struct ast_channel *chan);
 
@@ -131,39 +130,39 @@ extern int (*ast_adsi_begin_download)(struct ast_channel *chan, char *service, u
 
 extern int (*ast_adsi_end_download)(struct ast_channel *chan);
 
-/*! Restore ADSI initialization (for applications that play with ADSI */
-/*   and want to restore it to normal.  If you touch "INFO" then you */
-/*   have to use the ast_adsi_channel_init again instead. */
-/*!
+/*! Restore ADSI initialization (for applications that play with ADSI 
+ *   and want to restore it to normal.  If you touch "INFO" then you 
+ *   have to use the ast_adsi_channel_init again instead. 
  * \param chan Channel to restore
  *
- * Returns 0 on success (or adsi unavailable) and -1 on hangup
- *
+ * \retval 0 on success (or adsi unavailable)
+ * \retval -1 on hangup
  */
 extern int (*ast_adsi_channel_restore)(struct ast_channel *chan);
 
-/*! Display some stuff on the screen */
-/*!
+/*! 
+ * \brief Display some stuff on the screen 
  * \param chan Channel to display on
  * \param lines NULL-terminated list of things to print (no more than 4 recommended)
  * \param align list of alignments to use (ADSI_JUST_LEFT, ADSI_JUST_RIGHT, ADSI_JUST_CEN, etc..)
  * \param voice whether to jump into voice mode when finished
  *
- * Return 0 on success (or adsi unavailable) and -1 on hangup
- *
+ * \retval 0 on success (or adsi unavailable) 
+ * \retval -1 on hangup
  */
 extern int (*ast_adsi_print)(struct ast_channel *chan, char **lines, int *align, int voice);
 
-/*! Check if scripts for a given app are already loaded.  Version may be -1 */
-/*   if any version is okay, or 0-255 for a specific version. */
-/*!
+/*! 
+ * \brief Check if scripts for a given app are already loaded.
+ * Version may be -1, if any version is okay, or 0-255 for a specific version. 
  * \param chan Channel to test for loaded app
  * \param app Four character app name (must be unique to your application)
  * \param ver optional version number
  * \param data Non-zero if you want to be put in data mode
  *
- * Returns 0 if scripts is not loaded or not an ADSI CPE.  Returns -1
- * on hangup.  Returns 1 if script already loaded.
+ * \retval 0 if scripts is not loaded or not an ADSI CPE
+ * \retval -1 on hangup
+ * \retval 1 if script already loaded.
  */
 extern int (*ast_adsi_load_session)(struct ast_channel *chan, unsigned char *app, int ver, int data);
 extern int (*ast_adsi_unload_session)(struct ast_channel *chan);
@@ -172,35 +171,32 @@ extern int (*ast_adsi_unload_session)(struct ast_channel *chan);
 extern int (*ast_adsi_transmit_messages)(struct ast_channel *chan, unsigned char **msg, int *msglen, int *msgtype);
 extern int (*ast_adsi_transmit_message)(struct ast_channel *chan, unsigned char *msg, int msglen, int msgtype);
 extern int (*ast_adsi_transmit_message_full)(struct ast_channel *chan, unsigned char *msg, int msglen, int msgtype, int dowait);
-/*! Read some encoded DTMF data.   */
-/*!
+/*! Read some encoded DTMF data. 
  * Returns number of bytes received
  */
 extern int (*ast_adsi_read_encoded_dtmf)(struct ast_channel *chan, unsigned char *buf, int maxlen);
 
 /* ADSI Layer 3 creation functions */
 
-/*! Connects an ADSI Display Session */
-/*!
+/*! 
+ * \brief Connects an ADSI Display Session 
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  * \param fdn Optional 4 byte Feature Download Number (for loading soft keys)
  * \param ver Optional version number (0-255, or -1 to omit)
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
 
 extern int (*ast_adsi_connect_session)(unsigned char *buf, unsigned char *fdn, int ver);
 
-/*! Build Query CPE ID of equipment */
-/*!
+/*! Build Query CPE ID of equipment. 
  *  Returns number of bytes added to message
  */
 extern int (*ast_adsi_query_cpeid)(unsigned char *buf);
 extern int (*ast_adsi_query_cpeinfo)(unsigned char *buf);
 
-/*! Get CPE ID from an attached ADSI compatible CPE. */
-/*!
+/*! Get CPE ID from an attached ADSI compatible CPE. 
  * Returns 1 on success, storing 4 bytes of CPE ID at buf
  * or -1 on hangup, or 0 if there was no hangup but it failed to find the
  * device ID.  Returns to voice mode if "voice" is non-zero.
@@ -209,68 +205,67 @@ extern int (*ast_adsi_get_cpeid)(struct ast_channel *chan, unsigned char *cpeid,
 
 extern int (*ast_adsi_get_cpeinfo)(struct ast_channel *chan, int *width, int *height, int *buttons, int voice);
 
-/*! Begin an ADSI script download */
-/*!
+/*! 
+ * \brief Begin an ADSI script download 
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  * \param service a 1-18 byte name of the feature
  * \param fdn 4 byte Feature Download Number (for loading soft keys)
  * \param sec 4 byte vendor security code
  * \param ver version number (0-255, or -1 to omit)
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
 
 extern int (*ast_adsi_download_connect)(unsigned char *buf, char *service, unsigned char *fdn, unsigned char *sec, int ver);
 
-/*! Disconnects a running session */
-/*!
+/*! 
+ * \brief Disconnects a running session.
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
 extern int (*ast_adsi_disconnect_session)(unsigned char *buf);
 
-/*! Disconnects (and hopefully saves) a downloaded script */
-/*!
+/*! 
+ * \brief Disconnects (and hopefully saves) a downloaded script 
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
 extern int (*ast_adsi_download_disconnect)(unsigned char *buf);
 
-/*! Puts CPE in data mode... */
-/*!
+/*! 
+ * \brief Puts CPE in data mode.
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
 extern int (*ast_adsi_data_mode)(unsigned char *buf);
 extern int (*ast_adsi_clear_soft_keys)(unsigned char *buf);
 extern int (*ast_adsi_clear_screen)(unsigned char *buf);
 
-/*! Puts CPE in voice mode... */
-/*!
+/*! 
+ * \brief Puts CPE in voice mode.
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  * \param when (a time in seconds) to make the switch
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
 extern int (*ast_adsi_voice_mode)(unsigned char *buf, int when);
 
-/*! Returns non-zero if Channel does or might support ADSI */
-/*!
+/*! 
+ * \brief Returns non-zero if Channel does or might support ADSI 
  * \param chan Channel to check
- *
  */
 extern int (*ast_adsi_available)(struct ast_channel *chan);
 
-/*! Loads a line of info into the display */
-/*!
+/*! 
+ * \brief Loads a line of info into the display.
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  * \param page Page to load (ADSI_COMM_PAGE or ADSI_INFO_PAGE)
  * \param line Line number to load (1-4 for Comm page, 1-33 for info page)
@@ -279,26 +274,26 @@ extern int (*ast_adsi_available)(struct ast_channel *chan);
  * \param col1 Text to place in first column
  * \param col2 Text to place in second column
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
 
 extern int (*ast_adsi_display)(unsigned char *buf, int page, int line, int just, int wrap, char *col1, char *col2);
 
-/*! Sets the current line and page */
-/*!
+/*! 
+ * \brief Sets the current line and page. 
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  * \param page Which page (ADSI_COMM_PAGE or ADSI_INFO_PAGE)
  * \param line Line number (1-33 for info page, 1-4 for comm page)
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
 
 extern int (*ast_adsi_set_line)(unsigned char *buf, int page, int line);
 
-/*! Creates "load soft key" parameters */
-/*!
+/*! 
+ * \brief Creates "load soft key" parameters
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  * \param key Key code from 2 to 33, for which key we are loading
  * \param llabel Long label for key (1-18 bytes)
@@ -306,24 +301,24 @@ extern int (*ast_adsi_set_line)(unsigned char *buf, int page, int line);
  * \param ret Optional return sequence (NULL for none)
  * \param data whether to put CPE in data mode before sending digits
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
 extern int (*ast_adsi_load_soft_key)(unsigned char *buf, int key, const char *llabel, const char *slabel, char *ret, int data);
 
-/*! Set which soft keys should be displayed */
-/*!
+/*! 
+ * \brief Set which soft keys should be displayed 
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  * \param keys Array of 8 unsigned chars with the key numbers, may be OR'd with ADSI_KEY_HILITE
  *             But remember, the last two keys aren't real keys, they're for scrolling
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
 extern int (*ast_adsi_set_keys)(unsigned char *buf, unsigned char *keys);
 
-/*! Set input information */
-/*!
+/*! 
+ * \brief Set input information 
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  * \param page Which page to input on (ADSI_COMM_PAGE or ADSI_INFO_PAGE)
  * \param line Line number to input on
@@ -331,13 +326,13 @@ extern int (*ast_adsi_set_keys)(unsigned char *buf, unsigned char *keys);
  * \param format Format number to use (0-7)
  * \param just Justification (left, right center, indent)
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
 extern int (*ast_adsi_input_control)(unsigned char *buf, int page, int line, int display, int format, int just);
 
-/*! Set input format */
-/*!
+/*! 
+ * \brief Set input format 
  * \param buf Character buffer to create parameter in (must have at least 256 free)
  * \param num Which format we are setting
  * \param dir Which direction (ADSI_DIR_FROM_LEFT or ADSI_DIR_FROM_RIGHT)
@@ -345,8 +340,8 @@ extern int (*ast_adsi_input_control)(unsigned char *buf, int page, int line, int
  * \param format1 Format for column 1
  * \param format2 Format for column 2
  *
- * Returns number of bytes added to buffer or -1 on error.
- *
+ * \retval number of bytes added to buffer
+ * \retval -1 on error.
  */
 extern int (*ast_adsi_input_format)(unsigned char *buf, int num, int dir, int wrap, char *format1, char *format2);