[asterisk-commits] russell: trunk r75164 - /trunk/include/asterisk/
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Sun Jul 15 21:51:57 CDT 2007
Author: russell
Date: Sun Jul 15 21:51:56 2007
New Revision: 75164
URL: http://svn.digium.com/view/asterisk?view=rev&rev=75164
Log:
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)
Modified:
trunk/include/asterisk/abstract_jb.h
trunk/include/asterisk/adsi.h
trunk/include/asterisk/cdr.h
trunk/include/asterisk/channel.h
trunk/include/asterisk/cli.h
trunk/include/asterisk/config.h
trunk/include/asterisk/crypto.h
trunk/include/asterisk/devicestate.h
trunk/include/asterisk/doxyref.h
trunk/include/asterisk/dundi.h
trunk/include/asterisk/enum.h
trunk/include/asterisk/file.h
trunk/include/asterisk/frame.h
trunk/include/asterisk/image.h
trunk/include/asterisk/io.h
trunk/include/asterisk/jabber.h
trunk/include/asterisk/linkedlists.h
trunk/include/asterisk/manager.h
trunk/include/asterisk/module.h
trunk/include/asterisk/musiconhold.h
trunk/include/asterisk/pbx.h
trunk/include/asterisk/res_odbc.h
trunk/include/asterisk/say.h
trunk/include/asterisk/strings.h
trunk/include/asterisk/tdd.h
trunk/include/asterisk/translate.h
Modified: trunk/include/asterisk/abstract_jb.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/abstract_jb.h?view=diff&rev=75164&r1=75163&r2=75164
==============================================================================
--- trunk/include/asterisk/abstract_jb.h (original)
+++ trunk/include/asterisk/abstract_jb.h Sun Jul 15 21:51:56 2007
@@ -113,7 +113,8 @@
* appropriate internal jb flags to the channels, determining further behaviour
* of the bridged jitterbuffers.
*
- * \return zero if there are no jitter buffers in use, non-zero if there are
+ * \retval zero if there are no jitter buffers in use
+ * \retval non-zero if there are
*/
int ast_jb_do_usecheck(struct ast_channel *c0, struct ast_channel *c1);
@@ -150,7 +151,8 @@
* Dropped by the jb implementation frames are considered successfuly enqueued as
* far as they should not be delivered at all.
*
- * \return zero if the frame was queued, -1 if not.
+ * \retval 0 if the frame was queued
+ * \retval -1 if not
*/
int ast_jb_put(struct ast_channel *chan, struct ast_frame *f);
Modified: trunk/include/asterisk/adsi.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/adsi.h?view=diff&rev=75164&r1=75163&r2=75164
==============================================================================
--- trunk/include/asterisk/adsi.h (original)
+++ trunk/include/asterisk/adsi.h Sun Jul 15 21:51:56 2007
@@ -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_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_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_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 */
-/*!
- * \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.
- *
+/*!
+ * \brief Disconnects a running session.
+ * \param buf Character buffer to create parameter in (must have at least 256 free)
+ *
+ * \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 */
-/*!
- * \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.
- *
+/*!
+ * \brief Disconnects (and hopefully saves) a downloaded script
+ * \param buf Character buffer to create parameter in (must have at least 256 free)
+ *
+ * \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... */
-/*!
- * \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.
- *
+/*!
+ * \brief Puts CPE in data mode.
+ * \param buf Character buffer to create parameter in (must have at least 256 free)
+ *
+ * \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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);
Modified: trunk/include/asterisk/cdr.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/cdr.h?view=diff&rev=75164&r1=75163&r2=75164
==============================================================================
--- trunk/include/asterisk/cdr.h (original)
+++ trunk/include/asterisk/cdr.h Sun Jul 15 21:51:56 2007
@@ -84,12 +84,12 @@
char accountcode[AST_MAX_ACCOUNT_CODE];
/*! flags */
unsigned int flags;
- /* Unique Channel Identifier */
+ /*! Unique Channel Identifier */
char uniqueid[32];
- /* User field */
+ /*! User field */
char userfield[AST_MAX_USER_FIELD];
- /* A linked list for variables */
+ /*! A linked list for variables */
struct varshead varshead;
struct ast_cdr *next;
@@ -106,134 +106,141 @@
/*! \brief Return TRUE if CDR subsystem is enabled */
int check_cdr_enabled(void);
-/*! \brief Allocate a CDR record
- * Returns a malloc'd ast_cdr structure, returns NULL on error (malloc failure)
+/*!
+ * \brief Allocate a CDR record
+ * \retval a malloc'd ast_cdr structure
+ * \retval NULL on error (malloc failure)
*/
struct ast_cdr *ast_cdr_alloc(void);
-/*! \brief Duplicate a record
- * Returns a malloc'd ast_cdr structure, returns NULL on error (malloc failure)
+/*!
+ * \brief Duplicate a record
+ * \retval a malloc'd ast_cdr structure,
+ * \retval NULL on error (malloc failure)
*/
struct ast_cdr *ast_cdr_dup(struct ast_cdr *cdr);
-/*! \brief Free a CDR record
+/*!
+ * \brief Free a CDR record
* \param cdr ast_cdr structure to free
* Returns nothing
*/
void ast_cdr_free(struct ast_cdr *cdr);
-/*! \brief Discard and free a CDR record
+/*!
+ * \brief Discard and free a CDR record
* \param cdr ast_cdr structure to free
* Returns nothing -- same as free, but no checks or complaints
*/
void ast_cdr_discard(struct ast_cdr *cdr);
-/*! \brief Initialize based on a channel
+/*!
+ * \brief Initialize based on a channel
* \param cdr Call Detail Record to use for channel
* \param chan Channel to bind CDR with
* Initializes a CDR and associates it with a particular channel
- * Return is negligible. (returns 0 by default)
+ * \return 0 by default
*/
int ast_cdr_init(struct ast_cdr *cdr, struct ast_channel *chan);
-/*! Initialize based on a channel */
-/*!
+/*!
+ * \brief Initialize based on a channel
* \param cdr Call Detail Record to use for channel
* \param chan Channel to bind CDR with
* Initializes a CDR and associates it with a particular channel
- * Return is negligible. (returns 0 by default)
+ * \return 0 by default
*/
int ast_cdr_setcid(struct ast_cdr *cdr, struct ast_channel *chan);
-/*! Register a CDR handling engine */
-/*!
+/*!
+ * \brief Register a CDR handling engine
* \param name name associated with the particular CDR handler
* \param desc description of the CDR handler
* \param be function pointer to a CDR handler
* Used to register a Call Detail Record handler.
- * Returns -1 on error, 0 on success.
+ * \retval 0 on success.
+ * \retval -1 on error
*/
int ast_cdr_register(const char *name, const char *desc, ast_cdrbe be);
-/*! Unregister a CDR handling engine */
-/*!
+/*!
+ * \brief Unregister a CDR handling engine
* \param name name of CDR handler to unregister
* Unregisters a CDR by it's name
*/
void ast_cdr_unregister(const char *name);
-/*! Start a call */
-/*!
+/*!
+ * \brief Start a call
* \param cdr the cdr you wish to associate with the call
* Starts all CDR stuff necessary for monitoring a call
* Returns nothing
*/
void ast_cdr_start(struct ast_cdr *cdr);
-/*! Answer a call */
-/*!
+/*! \brief Answer a call
* \param cdr the cdr you wish to associate with the call
* Starts all CDR stuff necessary for doing CDR when answering a call
- * NULL argument is just fine.
+ * \note NULL argument is just fine.
*/
void ast_cdr_answer(struct ast_cdr *cdr);
-/*! A call wasn't answered */
-/*!
+/*!
+ * \brief A call wasn't answered
* \param cdr the cdr you wish to associate with the call
* Marks the channel disposition as "NO ANSWER"
*/
extern void ast_cdr_noanswer(struct ast_cdr *cdr);
-/*! Busy a call */
-/*!
+/*!
+ * \brief Busy a call
* \param cdr the cdr you wish to associate with the call
* Returns nothing
*/
void ast_cdr_busy(struct ast_cdr *cdr);
-/*! Fail a call */
-/*!
+/*!
+ * \brief Fail a call
* \param cdr the cdr you wish to associate with the call
* Returns nothing
*/
void ast_cdr_failed(struct ast_cdr *cdr);
-/*! Save the result of the call based on the AST_CAUSE_* */
-/*!
- * \param cdr the cdr you wish to associate with the call
- * Returns nothing
+/*!
+ * \brief Save the result of the call based on the AST_CAUSE_*
+ * \param cdr the cdr you wish to associate with the call
* \param cause the AST_CAUSE_*
+ * Returns nothing
*/
int ast_cdr_disposition(struct ast_cdr *cdr, int cause);
-/*! End a call */
-/*!
+/*!
+ * \brief End a call
* \param cdr the cdr you have associated the call with
* Registers the end of call time in the cdr structure.
* Returns nothing
*/
void ast_cdr_end(struct ast_cdr *cdr);
-/*! Detaches the detail record for posting (and freeing) either now or at a
- * later time in bulk with other records during batch mode operation */
-/*!
+/*!
+ * \brief Detaches the detail record for posting (and freeing) either now or at a
+ * later time in bulk with other records during batch mode operation.
* \param cdr Which CDR to detach from the channel thread
* Prevents the channel thread from blocking on the CDR handling
* Returns nothing
*/
void ast_cdr_detach(struct ast_cdr *cdr);
-/*! Spawns (possibly) a new thread to submit a batch of CDRs to the backend engines */
-/*!
+/*!
+ * \brief Spawns (possibly) a new thread to submit a batch of CDRs to the backend engines
* \param shutdown Whether or not we are shutting down
* Blocks the asterisk shutdown procedures until the CDR data is submitted.
* Returns nothing
*/
void ast_cdr_submit_batch(int shutdown);
-/*! Set the destination channel, if there was one */
-/*!
+/*!
+ * \brief Set the destination channel, if there was one
* \param cdr Which cdr it's applied to
* \param chan Channel to which dest will be
* Sets the destination channel the CDR is applied to
@@ -241,8 +248,8 @@
*/
void ast_cdr_setdestchan(struct ast_cdr *cdr, const char *chan);
-/*! Set the last executed application */
-/*!
+/*!
+ * \brief Set the last executed application
* \param cdr which cdr to act upon
* \param app the name of the app you wish to change it to
* \param data the data you want in the data field of app you set it to
@@ -251,40 +258,41 @@
*/
void ast_cdr_setapp(struct ast_cdr *cdr, char *app, char *data);
-/*! Convert a string to a detail record AMA flag */
-/*!
+/*!
+ * \brief Convert a string to a detail record AMA flag
* \param flag string form of flag
* Converts the string form of the flag to the binary form.
- * Returns the binary form of the flag
+ * \return the binary form of the flag
*/
int ast_cdr_amaflags2int(const char *flag);
-/*! Disposition to a string */
-/*!
+/*!
+ * \brief Disposition to a string
* \param disposition input binary form
* Converts the binary form of a disposition to string form.
- * Returns a pointer to the string form
+ * \return a pointer to the string form
*/
char *ast_cdr_disp2str(int disposition);
-/*! Reset the detail record, optionally posting it first */
-/*!
+/*!
+ * \brief Reset the detail record, optionally posting it first
* \param cdr which cdr to act upon
* \param flags |AST_CDR_FLAG_POSTED whether or not to post the cdr first before resetting it
* |AST_CDR_FLAG_LOCKED whether or not to reset locked CDR's
*/
void ast_cdr_reset(struct ast_cdr *cdr, struct ast_flags *flags);
-/*! Flags to a string */
-/*!
+/*!
+ * \brief Flags to a string
* \param flags binary flag
* Converts binary flags to string flags
* Returns string with flag name
*/
char *ast_cdr_flags2str(int flags);
-/*! Move the non-null data from the "from" cdr to the "to" cdr
- * \param to the cdr to get the goodies
+/*!
+ * \brief Move the non-null data from the "from" cdr to the "to" cdr
+ * \param to the cdr to get the goodies
* \param from the cdr to give the goodies
*/
void ast_cdr_merge(struct ast_cdr *to, struct ast_cdr *from);
@@ -297,7 +305,7 @@
int ast_cdr_appenduserfield(struct ast_channel *chan, const char *userfield);
-/* Update CDR on a channel */
+/*! Update CDR on a channel */
int ast_cdr_update(struct ast_channel *chan);
Modified: trunk/include/asterisk/channel.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/channel.h?view=diff&rev=75164&r1=75163&r2=75164
==============================================================================
--- trunk/include/asterisk/channel.h (original)
+++ trunk/include/asterisk/channel.h Sun Jul 15 21:51:56 2007
@@ -396,7 +396,7 @@
AST_STRING_FIELD(uniqueid); /*!< Unique Channel Identifier */
);
- /*! \brief File descriptor for channel -- Drivers will poll on these file descriptors, so at least one must be non -1. See \ref AstFileDesc */
+ /*! \brief File descriptor for channel -- Drivers will poll on these file descriptors, so at least one must be non -1. See \arg \ref AstFileDesc */
int fds[AST_MAX_FDS];
void *music_state; /*!< Music State*/
Modified: trunk/include/asterisk/cli.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/cli.h?view=diff&rev=75164&r1=75163&r2=75164
==============================================================================
--- trunk/include/asterisk/cli.h (original)
+++ trunk/include/asterisk/cli.h Sun Jul 15 21:51:56 2007
@@ -55,7 +55,7 @@
*/
#define ESS(x) ((x) == 1 ? "" : "s")
-/*! \page CLI_command_api CLI command API
+/*! \page CLI_command_API CLI command API
CLI commands are described by a struct ast_cli_entry that contains
all the components for their implementation.
@@ -123,8 +123,8 @@
*/
-/*! \brief calling arguments for new-style handlers
- See \ref CLI_command_API
+/*! \brief calling arguments for new-style handlers.
+* \arg \ref CLI_command_API
*/
enum ast_cli_fn {
CLI_INIT = -2, /* return the usage string */
@@ -147,8 +147,8 @@
typedef int (*old_cli_fn)(int fd, int argc, char *argv[]);
typedef char *(*new_cli_fn)(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);
-/*! \brief descriptor for a cli entry
- See \ref CLI_command_API
+/*! \brief descriptor for a cli entry.
+ * \arg \ref CLI_command_API
*/
struct ast_cli_entry {
char * const cmda[AST_MAX_CMD_LEN]; /*!< words making up the command.
@@ -217,16 +217,20 @@
*/
char *ast_cli_complete(const char *word, char *const choices[], int pos);
-/*! \brief Interprets a command
+/*!
+ * \brief Interprets a command
* Interpret a command s, sending output to fd
- * Returns 0 on succes, -1 on failure
+ * \retval 0 on success
+ * \retval -1 on failure
*/
int ast_cli_command(int fd, const char *s);
-/*! \brief Registers a command or an array of commands
+/*!
+ * \brief Registers a command or an array of commands
* \param e which cli entry to register
* Register your own command
- * Returns 0 on success, -1 on failure
+ * \retval 0 on success
+ * \retval -1 on failure
*/
int ast_cli_register(struct ast_cli_entry *e);
@@ -237,11 +241,11 @@
*/
int ast_cli_register_multiple(struct ast_cli_entry *e, int len);
-/*! \brief Unregisters a command or an array of commands
- *
+/*!
+ * \brief Unregisters a command or an array of commands
* \param e which cli entry to unregister
* Unregister your own command. You must pass a completed ast_cli_entry structure
- * Returns 0.
+ * \return 0.
*/
int ast_cli_unregister(struct ast_cli_entry *e);
@@ -252,9 +256,11 @@
*/
int ast_cli_unregister_multiple(struct ast_cli_entry *e, int len);
-/*! \brief Readline madness
+/*!
+ * \brief Readline madness
* Useful for readline, that's about it
- * Returns 0 on success, -1 on failure
+ * \retval 0 on success
+ * \retval -1 on failure
*/
char *ast_cli_generator(const char *, const char *, int);
Modified: trunk/include/asterisk/config.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/config.h?view=diff&rev=75164&r1=75163&r2=75164
==============================================================================
--- trunk/include/asterisk/config.h (original)
+++ trunk/include/asterisk/config.h Sun Jul 15 21:51:56 2007
@@ -70,7 +70,8 @@
* \param filename path of file to open. If no preceding '/' character, path is considered relative to AST_CONFIG_DIR
* Create a config structure from a given configuration file.
*
- * Returns NULL on error, or an ast_config data structure on success
+ * \retval an ast_config data structure on success
+ * \retval NULL on error
*/
struct ast_config *ast_config_load(const char *filename);
struct ast_config *ast_config_load_with_comments(const char *filename);
@@ -82,52 +83,62 @@
*/
void ast_config_destroy(struct ast_config *config);
-/*! \brief Goes through categories
+/*!
+ * \brief Goes through categories
* \param config Which config structure you wish to "browse"
* \param prev A pointer to a previous category.
* This funtion is kind of non-intuitive in it's use. To begin, one passes NULL as the second arguement. It will return a pointer to the string of the first category in the file. From here on after, one must then pass the previous usage's return value as the second pointer, and it will return a pointer to the category name afterwards.
*
- * Returns a category on success, or NULL on failure/no-more-categories
+ * \retval a category on success
+ * \retval NULL on failure/no-more-categories
*/
char *ast_category_browse(struct ast_config *config, const char *prev);
-/*! \brief Goes through variables
+/*!
+ * \brief Goes through variables
* Somewhat similar in intent as the ast_category_browse.
* List variables of config file category
*
- * Returns ast_variable list on success, or NULL on failure
+ * \retval ast_variable list on success
+ * \retval NULL on failure
*/
struct ast_variable *ast_variable_browse(const struct ast_config *config, const char *category);
-/*! \brief Gets a variable
+/*!
+ * \brief Gets a variable
* \param config which (opened) config to use
* \param category category under which the variable lies
* \param variable which variable you wish to get the data for
* Goes through a given config file in the given category and searches for the given variable
*
- * Returns the variable value on success, or NULL if unable to find it.
+ * \retval The variable value on success
+ * \retval NULL if unable to find it.
*/
const char *ast_variable_retrieve(const struct ast_config *config, const char *category, const char *variable);
-/*! \brief Retrieve a category if it exists
+/*!
+ * \brief Retrieve a category if it exists
* \param config which config to use
* \param category_name name of the category you're looking for
* This will search through the categories within a given config file for a match.
*
- * Returns pointer to category if found, NULL if not.
+ * \retval pointer to category if found
+ * \retval NULL if not.
*/
struct ast_category *ast_category_get(const struct ast_config *config, const char *category_name);
-/*! \brief Check for category duplicates
+/*!
+ * \brief Check for category duplicates
* \param config which config to use
* \param category_name name of the category you're looking for
* This will search through the categories within a given config file for a match.
*
- * Return non-zero if found
+ * \return non-zero if found
*/
int ast_category_exist(const struct ast_config *config, const char *category_name);
-/*! \brief Retrieve realtime configuration
+/*!
+ * \brief Retrieve realtime configuration
* \param family which family/config to lookup
* This will use builtin configuration backends to look up a particular
* entity in realtime and return a variable list of its parameters. Note
@@ -137,7 +148,8 @@
struct ast_variable *ast_load_realtime(const char *family, ...);
struct ast_variable *ast_load_realtime_all(const char *family, ...);
-/*! \brief Retrieve realtime configuration
+/*!
+ * \brief Retrieve realtime configuration
* \param family which family/config to lookup
* This will use builtin configuration backends to look up a particular
* entity in realtime and return a variable list of its parameters. Unlike
@@ -147,7 +159,8 @@
*/
struct ast_config *ast_load_realtime_multientry(const char *family, ...);
-/*! \brief Update realtime configuration
+/*!
+ * \brief Update realtime configuration
* \param family which family/config to be updated
* \param keyfield which field to use as the key
* \param lookup which value to look for in the key field to match the entry.
@@ -156,14 +169,16 @@
*/
int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...);
-/*! \brief Create realtime configuration
+/*!
+ * \brief Create realtime configuration
* \param family which family/config to be created
* This function is used to create a parameter in realtime configuration space.
*
*/
int ast_store_realtime(const char *family, ...);
-/*! \brief Destroy realtime configuration
+/*!
+ * \brief Destroy realtime configuration
* \param family which family/config to be destroyed
* \param keyfield which field to use as the key
* \param lookup which value to look for in the key field to match the entry.
@@ -173,9 +188,10 @@
*/
int ast_destroy_realtime(const char *family, const char *keyfield, const char *lookup, ...);
-/*! \brief Check if realtime engine is configured for family
- * returns 1 if family is configured in realtime and engine exists
+/*!
+ * \brief Check if realtime engine is configured for family
* \param family which family/config to be checked
+ * \return 1 if family is configured in realtime and engine exists
*/
int ast_check_realtime(const char *family);
Modified: trunk/include/asterisk/crypto.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/crypto.h?view=diff&rev=75164&r1=75163&r2=75164
==============================================================================
--- trunk/include/asterisk/crypto.h (original)
+++ trunk/include/asterisk/crypto.h Sun Jul 15 21:51:56 2007
@@ -32,76 +32,90 @@
struct ast_key;
-/*! \brief Retrieve a key
+/*!
+ * \brief Retrieve a key
* \param name of the key we are retrieving
* \param int type of key (AST_KEY_PUBLIC or AST_KEY_PRIVATE)
*
- * Returns the key on success or NULL on failure
+ * \retval the key on success.
+ * \retval NULL on failure.
*/
struct ast_key *(*ast_key_get)(const char *key, int type);
-/*! \brief Check the authenticity of a message signature using a given public key
+/*!
+ * \brief Check the authenticity of a message signature using a given public key
* \param key a public key to use to verify
* \param msg the message that has been signed
* \param sig the proposed valid signature in mime64-like encoding
*
- * Returns 0 if the signature is valid, or -1 otherwise
+ * \retval 0 if the signature is valid.
+ * \retval -1 otherwise.
*
*/
int (*ast_check_signature)(struct ast_key *key, const char *msg, const char *sig);
-/*! \brief Check the authenticity of a message signature using a given public key
+/*!
+ * \brief Check the authenticity of a message signature using a given public key
* \param key a public key to use to verify
* \param msg the message that has been signed
* \param sig the proposed valid signature in raw binary representation
*
- * Returns 0 if the signature is valid, or -1 otherwise
+ * \retval 0 if the signature is valid.
+ * \retval -1 otherwise.
*
*/
int (*ast_check_signature_bin)(struct ast_key *key, const char *msg, int msglen, const unsigned char *sig);
/*!
+ * \brief Sign a message signature using a given private key
* \param key a private key to use to create the signature
* \param msg the message to sign
* \param sig a pointer to a buffer of at least 256 bytes in which the
* mime64-like encoded signature will be stored
*
- * Returns 0 on success or -1 on failure.
+ * \retval 0 on success.
+ * \retval -1 on failure.
*
*/
int (*ast_sign)(struct ast_key *key, char *msg, char *sig);
/*!
+ * \brief Sign a message signature using a given private key
* \param key a private key to use to create the signature
* \param msg the message to sign
* \param sig a pointer to a buffer of at least 128 bytes in which the
* raw encoded signature will be stored
*
- * Returns 0 on success or -1 on failure.
+ * \retval 0 on success.
+ * \retval -1 on failure.
*
*/
int (*ast_sign_bin)(struct ast_key *key, const char *msg, int msglen, unsigned char *sig);
/*!
+ * \brief Encrypt a message using a given private key
* \param key a private key to use to encrypt
* \param src the message to encrypt
* \param srclen the length of the message to encrypt
* \param dst a pointer to a buffer of at least srclen * 1.5 bytes in which the encrypted
* answer will be stored
*
- * Returns length of encrypted data on success or -1 on failure.
+ * \retval length of encrypted data on success.
+ * \retval -1 on failure.
*
*/
int (*ast_encrypt_bin)(unsigned char *dst, const unsigned char *src, int srclen, struct ast_key *key);
/*!
+ * \brief Decrypt a message using a given private key
* \param key a private key to use to decrypt
* \param src the message to decrypt
* \param srclen the length of the message to decrypt
* \param dst a pointer to a buffer of at least srclen bytes in which the decrypted
* answer will be stored
*
- * Returns length of decrypted data on success or -1 on failure.
+ * \retval length of dencrypted data on success.
+ * \retval -1 on failure.
*
*/
int (*ast_decrypt_bin)(unsigned char *dst, const unsigned char *src, int srclen, struct ast_key *key);
Modified: trunk/include/asterisk/devicestate.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/devicestate.h?view=diff&rev=75164&r1=75163&r2=75164
==============================================================================
--- trunk/include/asterisk/devicestate.h (original)
+++ trunk/include/asterisk/devicestate.h Sun Jul 15 21:51:56 2007
@@ -78,53 +78,63 @@
*/
enum ast_device_state ast_devstate_val(const char *val);
-/*! \brief Search the Channels by Name
+/*!
+ * \brief Search the Channels by Name
* \param device like a dialstring
* Search the Device in active channels by compare the channelname against
* the devicename. Compared are only the first chars to the first '-' char.
- * Returns an AST_DEVICE_UNKNOWN if no channel found or
- * AST_DEVICE_INUSE if a channel is found
+ * \retval an AST_DEVICE_UNKNOWN if no channel found
+ * \retval AST_DEVICE_INUSE if a channel is found
*/
enum ast_device_state ast_parse_device_state(const char *device);
-/*! \brief Asks a channel for device state
+/*!
+ * \brief Asks a channel for device state
* \param device like a dialstring
* Asks a channel for device state, data is normaly a number from dialstring
* used by the low level module
* Trys the channel devicestate callback if not supported search in the
* active channels list for the device.
- * Returns an AST_DEVICE_??? state -1 on failure
+ * \retval an AST_DEVICE_??? state
+ * \retval -1 on failure
*/
enum ast_device_state ast_device_state(const char *device);
-/*! \brief Tells Asterisk the State for Device is changed
+/*!
+ * \brief Tells Asterisk the State for Device is changed
* \param fmt devicename like a dialstring with format parameters
* Asterisk polls the new extensionstates and calls the registered
* callbacks for the changed extensions
- * Returns 0 on success, -1 on failure
+ * \retval 0 on success
+ * \retval -1 on failure
*/
int ast_device_state_changed(const char *fmt, ...)
__attribute__ ((format (printf, 1, 2)));
-/*! \brief Tells Asterisk the State for Device is changed
+/*!
+ * \brief Tells Asterisk the State for Device is changed
* \param device devicename like a dialstring
* Asterisk polls the new extensionstates and calls the registered
* callbacks for the changed extensions
- * Returns 0 on success, -1 on failure
+ * \retval 0 on success
+ * \retval -1 on failure
*/
int ast_device_state_changed_literal(const char *device);
-/*! \brief Add device state provider
+/*!
+ * \brief Add device state provider
* \param label to use in hint, like label:object
* \param callback Callback
+ * \retval 0 success
* \retval -1 failure
- * \retval 0 success
*/
int ast_devstate_prov_add(const char *label, ast_devstate_prov_cb_type callback);
-/*! \brief Remove device state provider
+/*!
+ * \brief Remove device state provider
* \param label to use in hint, like label:object
- * Return -1 on failure, 0 on success
+ * \retval 0 on success
+ * \retval -1 on failure
*/
int ast_devstate_prov_del(const char *label);
Modified: trunk/include/asterisk/doxyref.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/doxyref.h?view=diff&rev=75164&r1=75163&r2=75164
==============================================================================
--- trunk/include/asterisk/doxyref.h (original)
+++ trunk/include/asterisk/doxyref.h Sun Jul 15 21:51:56 2007
@@ -500,19 +500,21 @@
/*! \addtogroup cdr_drivers Module: CDR Drivers
* \section CDR_generic Asterisk CDR Drivers
[... 1325 lines stripped ...]
More information about the asterisk-commits
mailing list