[asterisk-commits] rmudgett: branch group/issue8824 r180785 - /team/group/issue8824/include/aste...

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Mon Mar 9 18:31:46 CDT 2009


Author: rmudgett
Date: Mon Mar  9 18:31:43 2009
New Revision: 180785

URL: http://svn.digium.com/svn-view/asterisk?view=rev&rev=180785
Log:
Better conflict resolution plus some other comment changes

Modified:
    team/group/issue8824/include/asterisk/callerid.h
    team/group/issue8824/include/asterisk/channel.h

Modified: team/group/issue8824/include/asterisk/callerid.h
URL: http://svn.digium.com/svn-view/asterisk/team/group/issue8824/include/asterisk/callerid.h?view=diff&rev=180785&r1=180784&r2=180785
==============================================================================
--- team/group/issue8824/include/asterisk/callerid.h (original)
+++ team/group/issue8824/include/asterisk/callerid.h Mon Mar  9 18:31:43 2009
@@ -176,13 +176,14 @@
  */
 int ast_callerid_generate(unsigned char *buf, const char *name, const char *number, int codec);
 
-/*! \brief Generate message waiting indicator
- *  \param active The message indicator state
+/*!
+ * \brief Generate message waiting indicator
+ * \param active The message indicator state
  *  -- either 0 no messages in mailbox or 1 messages in mailbox
- *  \param type Format of message (any of CID_MWI_TYPE_*)
- *  \see callerid_generate() for more info as it use the same encoding
- *  \version 1.6.1 changed mdmf parameter to type, added name, number and flags for caller id message generation
-*/
+ * \param type Format of message (any of CID_MWI_TYPE_*)
+ * \see callerid_generate() for more info as it uses the same encoding
+ * \version 1.6.1 changed mdmf parameter to type, added name, number and flags for caller id message generation
+ */
 int vmwi_generate(unsigned char *buf, int active, int type, int codec, const char *name,
 	const char *number, int flags);
 
@@ -391,7 +392,7 @@
 const char *ast_redirecting_reason_describe(int data);
 const char *ast_redirecting_reason_name(int data);
 
-/*! 
+/*!
  * \brief Connected line update source code
  */
 enum AST_CONNECTED_LINE_UPDATE_SOURCE {

Modified: team/group/issue8824/include/asterisk/channel.h
URL: http://svn.digium.com/svn-view/asterisk/team/group/issue8824/include/asterisk/channel.h?view=diff&rev=180785&r1=180784&r2=180785
==============================================================================
--- team/group/issue8824/include/asterisk/channel.h (original)
+++ team/group/issue8824/include/asterisk/channel.h Mon Mar  9 18:31:43 2009
@@ -187,12 +187,13 @@
 	void (*digit)(struct ast_channel *chan, char digit);
 };
 
-/*! \brief Structure for all kinds of caller ID identifications.
+/*!
+ * \brief Structure for all kinds of caller ID identifications.
  * \note All string fields here are malloc'ed, so they need to be
  * freed when the structure is deleted.
  * Also, NULL and "" must be considered equivalent.
  *
- * SIP and IAX2 has utf8 encoded Unicode caller ID names.
+ * \note SIP and IAX2 has utf8 encoded Unicode caller ID names.
  * In some cases, we also have an alternative (RPID) E.164 number that can be used
  * as caller ID on numeric E.164 phone networks (DAHDI or SIP/IAX2 to PSTN gateway).
  *
@@ -273,6 +274,7 @@
 struct ast_party_id {
 	/*! \brief Subscriber phone number (Malloced) */
 	char *number;
+
 	/*! \brief Subscriber name (Malloced) */
 	char *name;
 
@@ -283,7 +285,8 @@
 	int number_presentation;
 };
 
-/*! \brief Connected Line/Party information.
+/*!
+ * \brief Connected Line/Party information.
  * \note All string fields here are malloc'ed, so they need to be
  * freed when the structure is deleted.
  * \note NULL and "" must be considered equivalent.
@@ -312,7 +315,8 @@
 	int source;
 };
 
-/*! \brief Redirecting Line information.
+/*!
+ * \brief Redirecting Line information.
  * RDNIS (Redirecting Directory Number Information Service)
  * Where a call diversion or transfer was invoked.
  * \note All string fields here are malloc'ed, so they need to be
@@ -333,7 +337,8 @@
 	int reason;
 };
 
-/*! \brief
+/*!
+ * \brief
  * Structure to describe a channel "technology", ie a channel driver
  * See for examples:
  * \arg chan_iax2.c - The Inter-Asterisk exchange protocol
@@ -505,7 +510,8 @@
 	T38_STATE_NEGOTIATED,	/*!< T38 established */
 };
 
-/*! \brief Main Channel structure associated with a channel.
+/*!
+ * \brief Main Channel structure associated with a channel.
  * This is the side of it mostly used by the pbx and call management.
  *
  * \note XXX It is important to remember to increment .cleancount each time
@@ -653,11 +659,15 @@
 
 /*! \brief ast_channel_tech Properties */
 enum {
-	/*! \brief Channels have this property if they can accept input with jitter;
-	 *         i.e. most VoIP channels */
+	/*!
+     * \brief Channels have this property if they can accept input with jitter;
+	 * i.e. most VoIP channels
+	 */
 	AST_CHAN_TP_WANTSJITTER = (1 << 0),
-	/*! \brief Channels have this property if they can create jitter;
-	 *         i.e. most VoIP channels */
+	/*!
+     * \brief Channels have this property if they can create jitter;
+	 * i.e. most VoIP channels
+	 */
 	AST_CHAN_TP_CREATESJITTER = (1 << 1),
 };
 
@@ -956,6 +966,7 @@
  * \param data data to pass to the channel requester
  * \param status status
  *
+ * \details
  * Request a channel of a given type, with data as optional information used
  * by the low level module
  *
@@ -999,54 +1010,63 @@
 struct ast_channel *__ast_request_and_dial(const char *type, int format, void *data,
 	int timeout, int *reason, const char *cid_num, const char *cid_name, struct outgoing_helper *oh);
 
-/*! \brief Register a channel technology (a new channel driver)
+/*!
+ * \brief Register a channel technology (a new channel driver)
  * Called by a channel module to register the kind of channels it supports.
  * \param tech Structure defining channel technology or "type"
  * \return Returns 0 on success, -1 on failure.
  */
 int ast_channel_register(const struct ast_channel_tech *tech);
 
-/*! \brief Unregister a channel technology
+/*!
+ * \brief Unregister a channel technology
  * \param tech Structure defining channel technology or "type" that was previously registered
  * \return No return value.
  */
 void ast_channel_unregister(const struct ast_channel_tech *tech);
 
-/*! \brief Get a channel technology structure by name
+/*!
+ * \brief Get a channel technology structure by name
  * \param name name of technology to find
  * \return a pointer to the structure, or NULL if no matching technology found
  */
 const struct ast_channel_tech *ast_get_channel_tech(const char *name);
 
 #ifdef CHANNEL_TRACE
-/*! \brief Update the context backtrace if tracing is enabled
+/*!
+ * \brief Update the context backtrace if tracing is enabled
  * \return Returns 0 on success, -1 on failure
  */
 int ast_channel_trace_update(struct ast_channel *chan);
 
-/*! \brief Enable context tracing in the channel
+/*!
+ * \brief Enable context tracing in the channel
  * \return Returns 0 on success, -1 on failure
  */
 int ast_channel_trace_enable(struct ast_channel *chan);
 
-/*! \brief Disable context tracing in the channel.
+/*!
+ * \brief Disable context tracing in the channel.
  * \note Does not remove current trace entries
  * \return Returns 0 on success, -1 on failure
  */
 int ast_channel_trace_disable(struct ast_channel *chan);
 
-/*! \brief Whether or not context tracing is enabled
+/*!
+ * \brief Whether or not context tracing is enabled
  * \return Returns -1 when the trace is enabled. 0 if not.
  */
 int ast_channel_trace_is_enabled(struct ast_channel *chan);
 
-/*! \brief Put the channel backtrace in a string
+/*!
+ * \brief Put the channel backtrace in a string
  * \return Returns the amount of lines in the backtrace. -1 on error.
  */
 int ast_channel_trace_serialize(struct ast_channel *chan, struct ast_str **out);
 #endif
 
-/*! \brief Hang up a channel
+/*!
+ * \brief Hang up a channel
  * \note This function performs a hard hangup on a channel.  Unlike the soft-hangup, this function
  * performs all stream stopping, etc, on the channel that needs to end.
  * chan is no longer valid after this call.
@@ -1061,6 +1081,7 @@
  * \param chan channel to be soft-hung-up
  * \param cause	Ast hangupcause for hangup
  *
+ * \details
  * Call the protocol layer, but don't destroy the channel structure
  * (use this if you are trying to
  * safely hangup a channel managed by another thread.
@@ -1071,9 +1092,11 @@
  */
 int ast_softhangup(struct ast_channel *chan, int cause);
 
-/*! \brief Softly hangup up a channel (no channel lock)
+/*!
+ * \brief Softly hangup up a channel (no channel lock)
  * \param chan channel to be soft-hung-up
- * \param cause	Ast hangupcause for hangup (see cause.h) */
+ * \param cause	Ast hangupcause for hangup (see cause.h)
+ */
 int ast_softhangup_nolock(struct ast_channel *chan, int cause);
 
 /*! \brief Check to see if a channel is needing hang up
@@ -1088,6 +1111,7 @@
  * \param chan channel on which to check for hang up
  * \param offset offset in seconds from current time
  * \return 1, 0, or -1
+ * \details
  * This function compares a offset from current time with the absolute time
  * out on a channel (when to hang up). If the absolute time out on a channel
  * is earlier than current time plus the offset, it returns 1, if the two
@@ -1110,7 +1134,8 @@
  */
 int ast_channel_cmpwhentohangup_tv(struct ast_channel *chan, struct timeval offset);
 
-/*! \brief Set when to hang a channel up
+/*!
+ * \brief Set when to hang a channel up
  *
  * \param chan channel on which to check for hang up
  * \param offset offset in seconds relative to the current time of when to hang up
@@ -1127,7 +1152,8 @@
  */
 void ast_channel_setwhentohangup(struct ast_channel *chan, time_t offset) __attribute__((deprecated));
 
-/*! \brief Set when to hang a channel up
+/*!
+ * \brief Set when to hang a channel up
  *
  * \param chan channel on which to check for hang up
  * \param offset offset in seconds and useconds relative to the current time of when to hang up
@@ -1159,18 +1185,21 @@
 int ast_answer(struct ast_channel *chan);
 int __ast_answer(struct ast_channel *chan, unsigned int delay, int cdr_answer);
 
-/*! \brief Make a call
+/*!
+ * \brief Make a call
  * \param chan which channel to make the call on
  * \param addr destination of the call
  * \param timeout time to wait on for connect
+ * \details
  * Place a call, take no longer than timeout ms.
-   \return Returns -1 on failure, 0 on not enough time
-   (does not automatically stop ringing), and
-   the number of seconds the connect took otherwise.
-   */
+ * \return -1 on failure, 0 on not enough time
+ * (does not automatically stop ringing), and
+ * the number of seconds the connect took otherwise.
+ */
 int ast_call(struct ast_channel *chan, char *addr, int timeout);
 
-/*! \brief Indicates condition of channel
+/*!
+ * \brief Indicates condition of channel
  * \note Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel
  * \param chan channel to change the indication
  * \param condition which condition to indicate on the channel
@@ -1178,7 +1207,8 @@
  */
 int ast_indicate(struct ast_channel *chan, int condition);
 
-/*! \brief Indicates condition of channel, with payload
+/*!
+ * \brief Indicates condition of channel, with payload
  * \note Indicate a condition such as AST_CONTROL_HOLD with payload being music on hold class
  * \param chan channel to change the indication
  * \param condition which condition to indicate on the channel
@@ -1190,14 +1220,20 @@
 
 /* Misc stuff ------------------------------------------------ */
 
-/*! \brief Wait for input on a channel
+/*!
+ * \brief Wait for input on a channel
  * \param chan channel to wait on
  * \param ms length of time to wait on the channel
+ * \details
  * Wait for input on a channel for a given # of milliseconds (<0 for indefinite).
-  \return Returns < 0 on  failure, 0 if nothing ever arrived, and the # of ms remaining otherwise */
+ * \retval < 0 on failure
+ * \retval 0 if nothing ever arrived
+ * \retval the # of ms remaining otherwise
+ */
 int ast_waitfor(struct ast_channel *chan, int ms);
 
-/*! \brief Wait for a specified amount of time, looking for hangups
+/*!
+ * \brief Wait for a specified amount of time, looking for hangups
  * \param chan channel to wait for
  * \param ms length of time in milliseconds to sleep
  * \details
@@ -1206,7 +1242,8 @@
  */
 int ast_safe_sleep(struct ast_channel *chan, int ms);
 
-/*! \brief Wait for a specified amount of time, looking for hangups and a condition argument
+/*!
+ * \brief Wait for a specified amount of time, looking for hangups and a condition argument
  * \param chan channel to wait for
  * \param ms length of time in milliseconds to sleep
  * \param cond a function pointer for testing continue condition
@@ -1218,7 +1255,8 @@
  */
 int ast_safe_sleep_conditional(struct ast_channel *chan, int ms, int (*cond)(void*), void *data );
 
-/*! \brief Waits for activity on a group of channels
+/*!
+ * \brief Waits for activity on a group of channels
  * \param chan an array of pointers to channels
  * \param n number of channels that are to be waited upon
  * \param fds an array of fds to wait upon
@@ -1236,21 +1274,25 @@
 struct ast_channel *ast_waitfor_nandfds(struct ast_channel **chan, int n,
 	int *fds, int nfds, int *exception, int *outfd, int *ms);
 
-/*! \brief Waits for input on a group of channels
-   Wait for input on an array of channels for a given # of milliseconds.
-	\return Return channel with activity, or NULL if none has activity.
-	\param chan an array of pointers to channels
-	\param n number of channels that are to be waited upon
-	\param ms time "ms" is modified in-place, if applicable */
+/*!
+ * \brief Waits for input on a group of channels
+ * Wait for input on an array of channels for a given # of milliseconds.
+ * \return Return channel with activity, or NULL if none has activity.
+ * \param chan an array of pointers to channels
+ * \param n number of channels that are to be waited upon
+ * \param ms time "ms" is modified in-place, if applicable
+ */
 struct ast_channel *ast_waitfor_n(struct ast_channel **chan, int n, int *ms);
 
-/*! \brief Waits for input on an fd
- * This version works on fd's only.  Be careful with it.
+/*!
+ * \brief Waits for input on an fd
+ * \note This version works on fd's only.  Be careful with it.
  */
 int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception);
 
 
-/*! \brief Reads a frame
+/*!
+ * \brief Reads a frame
  * \param chan channel to read a frame from
  * \return Returns a frame, or NULL on error.  If it returns NULL, you
  * best just stop reading frames and assume the channel has been
@@ -1258,16 +1300,19 @@
  */
 struct ast_frame *ast_read(struct ast_channel *chan);
 
-/*! \brief Reads a frame, returning AST_FRAME_NULL frame if audio.
- 	\param chan channel to read a frame from
-	\return  Returns a frame, or NULL on error.  If it returns NULL, you
-		best just stop reading frames and assume the channel has been
-		disconnected.
-	\note Audio is replaced with AST_FRAME_NULL to avoid
-	transcode when the resulting audio is not necessary. */
+/*!
+ * \brief Reads a frame, returning AST_FRAME_NULL frame if audio.
+ * \param chan channel to read a frame from
+ * \return  Returns a frame, or NULL on error.  If it returns NULL, you
+ * best just stop reading frames and assume the channel has been
+ * disconnected.
+ * \note Audio is replaced with AST_FRAME_NULL to avoid
+ * transcode when the resulting audio is not necessary.
+ */
 struct ast_frame *ast_read_noaudio(struct ast_channel *chan);
 
-/*! \brief Write a frame to a channel
+/*!
+ * \brief Write a frame to a channel
  * This function writes the given frame to the indicated channel.
  * \param chan destination channel of the frame
  * \param frame frame that will be written
@@ -1275,7 +1320,8 @@
  */
 int ast_write(struct ast_channel *chan, struct ast_frame *frame);
 
-/*! \brief Write video frame to a channel
+/*!
+ * \brief Write video frame to a channel
  * This function writes the given frame to the indicated channel.
  * \param chan destination channel of the frame
  * \param frame frame that will be written
@@ -1283,7 +1329,8 @@
  */
 int ast_write_video(struct ast_channel *chan, struct ast_frame *frame);
 
-/*! \brief Write text frame to a channel
+/*!
+ * \brief Write text frame to a channel
  * This function writes the given frame to the indicated channel.
  * \param chan destination channel of the frame
  * \param frame frame that will be written
@@ -1294,7 +1341,8 @@
 /*! \brief Send empty audio to prime a channel driver */
 int ast_prod(struct ast_channel *chan);
 
-/*! \brief Sets read format on channel chan
+/*!
+ * \brief Sets read format on channel chan
  * Set read format for channel to whichever component of "format" is best.
  * \param chan channel to change
  * \param format format to change to
@@ -1302,7 +1350,8 @@
  */
 int ast_set_read_format(struct ast_channel *chan, int format);
 
-/*! \brief Sets write format on channel chan
+/*!
+ * \brief Sets write format on channel chan
  * Set write format for channel to whichever component of "format" is best.
  * \param chan channel to change
  * \param format new format for writing
@@ -1326,7 +1375,8 @@
  */
 int ast_sendtext(struct ast_channel *chan, const char *text);
 
-/*! \brief Receives a text character from a channel
+/*!
+ * \brief Receives a text character from a channel
  * \param chan channel to act upon
  * \param timeout timeout in milliseconds (0 for infinite wait)
  * \details
@@ -1335,7 +1385,8 @@
  */
 int ast_recvchar(struct ast_channel *chan, int timeout);
 
-/*! \brief Send a DTMF digit to a channel.
+/*!
+ * \brief Send a DTMF digit to a channel.
  * \param chan channel to act upon
  * \param digit the DTMF digit to send, encoded in ASCII
  * \param duration the duration of the digit ending in ms
@@ -1343,14 +1394,16 @@
  */
 int ast_senddigit(struct ast_channel *chan, char digit, unsigned int duration);
 
-/*! \brief Send a DTMF digit to a channel.
+/*!
+ * \brief Send a DTMF digit to a channel.
  * \param chan channel to act upon
  * \param digit the DTMF digit to send, encoded in ASCII
  * \return 0 on success, -1 on failure
  */
 int ast_senddigit_begin(struct ast_channel *chan, char digit);
 
-/*! \brief Send a DTMF digit to a channel.
+/*!
+ * \brief Send a DTMF digit to a channel.
  * \param chan channel to act upon
  * \param digit the DTMF digit to send, encoded in ASCII
  * \param duration the duration of the digit ending in ms
@@ -1358,7 +1411,8 @@
  */
 int ast_senddigit_end(struct ast_channel *chan, char digit, unsigned int duration);
 
-/*! \brief Receives a text string from a channel
+/*!
+ * \brief Receives a text string from a channel
  * Read a string of text from a channel
  * \param chan channel to act upon
  * \param timeout timeout in milliseconds (0 for infinite wait)
@@ -1366,7 +1420,8 @@
  */
 char *ast_recvtext(struct ast_channel *chan, int timeout);
 
-/*! \brief Browse channels in use
+/*!
+ * \brief Browse channels in use
  * Browse the channels currently in use
  * \param prev where you want to start in the channel list
  * \return Returns the next channel in the list, NULL on end.
@@ -1390,7 +1445,8 @@
 struct ast_channel *ast_walk_channel_by_exten_locked(const struct ast_channel *chan, const char *exten,
 						     const char *context);
 
-/*! \brief Search for a channel based on the passed channel matching callback
+/*!
+ * \brief Search for a channel based on the passed channel matching callback
  * Search for a channel based on the specified is_match callback, and return the
  * first channel that we match.  When returned, the channel will be locked.  Note
  * that the is_match callback is called with the passed channel locked, and should
@@ -1402,33 +1458,41 @@
  */
 struct ast_channel *ast_channel_search_locked(int (*is_match)(struct ast_channel *, void *), void *data);
 
-/*! \brief Waits for a digit
+/*!
+ * \brief Waits for a digit
  * \param c channel to wait for a digit on
  * \param ms how many milliseconds to wait
- * \return Returns <0 on error, 0 on no entry, and the digit on success. */
+ * \return Returns <0 on error, 0 on no entry, and the digit on success.
+ */
 int ast_waitfordigit(struct ast_channel *c, int ms);
 
-/*! \brief Wait for a digit
- Same as ast_waitfordigit() with audio fd for outputting read audio and ctrlfd to monitor for reading.
+/*!
+ * \brief Wait for a digit
+ * Same as ast_waitfordigit() with audio fd for outputting read audio and ctrlfd to monitor for reading.
  * \param c channel to wait for a digit on
  * \param ms how many milliseconds to wait
  * \param audiofd audio file descriptor to write to if audio frames are received
  * \param ctrlfd control file descriptor to monitor for reading
- * \return Returns 1 if ctrlfd becomes available */
+ * \return Returns 1 if ctrlfd becomes available
+ */
 int ast_waitfordigit_full(struct ast_channel *c, int ms, int audiofd, int ctrlfd);
 
-/*! Reads multiple digits
+/*!
+ * \brief Reads multiple digits
  * \param c channel to read from
  * \param s string to read in to.  Must be at least the size of your length
  * \param len how many digits to read (maximum)
  * \param timeout how long to timeout between digits
  * \param rtimeout timeout to wait on the first digit
  * \param enders digits to end the string
+ * \details
  * Read in a digit string "s", max length "len", maximum timeout between
-   digits "timeout" (-1 for none), terminated by anything in "enders".  Give them rtimeout
-   for the first digit.  Returns 0 on normal return, or 1 on a timeout.  In the case of
-   a timeout, any digits that were read before the timeout will still be available in s.
-   RETURNS 2 in full version when ctrlfd is available, NOT 1*/
+ * digits "timeout" (-1 for none), terminated by anything in "enders".  Give them rtimeout
+ * for the first digit.
+ * \return Returns 0 on normal return, or 1 on a timeout.  In the case of
+ * a timeout, any digits that were read before the timeout will still be available in s.
+ * RETURNS 2 in full version when ctrlfd is available, NOT 1
+ */
 int ast_readstring(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders);
 int ast_readstring_full(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders, int audiofd, int ctrlfd);
 
@@ -1444,22 +1508,28 @@
 #define AST_BRIDGE_IGNORE_SIGS			(1 << 4)
 
 
-/*! \brief Makes two channel formats compatible
+/*!
+ * \brief Makes two channel formats compatible
  * \param c0 first channel to make compatible
  * \param c1 other channel to make compatible
- * Set two channels to compatible formats -- call before ast_channel_bridge in general .
- * \return Returns 0 on success and -1 if it could not be done */
+ * \details
+ * Set two channels to compatible formats -- call before ast_channel_bridge in general.
+ * \return Returns 0 on success and -1 if it could not be done
+ */
 int ast_channel_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
 
-/*! \brief Bridge two channels together (early)
+/*!
+ * \brief Bridge two channels together (early)
  * \param c0 first channel to bridge
  * \param c1 second channel to bridge
  * \details
  * Bridge two channels (c0 and c1) together early. This implies either side may not be answered yet.
- * \return Returns 0 on success and -1 if it could not be done */
+ * \return Returns 0 on success and -1 if it could not be done
+ */
 int ast_channel_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
 
-/*! Bridge two channels together
+/*!
+ * \brief Bridge two channels together
  * \param c0 first channel to bridge
  * \param c1 second channel to bridge
  * \param config config for the channels
@@ -1491,49 +1561,56 @@
  */
 int ast_channel_masquerade(struct ast_channel *original, struct ast_channel *clone);
 
-/*! Gives the string form of a given cause code */
-/*!
+/*!
+ * \brief Gives the string form of a given cause code.
+ *
  * \param state cause to get the description of
  * \return the text form of the binary cause code given
  */
 const char *ast_cause2str(int state) attribute_pure;
 
-/*! Convert the string form of a cause code to a number */
-/*!
+/*!
+ * \brief Convert the string form of a cause code to a number
+ *
  * \param name string form of the cause
  * \return the cause code
  */
 int ast_str2cause(const char *name) attribute_pure;
 
-/*! Gives the string form of a given channel state */
-/*!
+/*!
+ * \brief Gives the string form of a given channel state
+ *
  * \param ast_channel_state state to get the name of
- * Give a name to a state
- * Returns the text form of the binary state given
+ * \return the text form of the binary state given
  */
 const char *ast_state2str(enum ast_channel_state);
 
-/*! \brief Gives the string form of a given transfer capability
+/*!
+ * \brief Gives the string form of a given transfer capability
  *
  * \param transfercapability transfer capability to get the name of
  * \return the text form of the binary transfer capability
  */
 char *ast_transfercapability2str(int transfercapability) attribute_const;
 
-/* Options: Some low-level drivers may implement "options" allowing fine tuning of the
-   low level channel.  See frame.h for options.  Note that many channel drivers may support
-   none or a subset of those features, and you should not count on this if you want your
-   asterisk application to be portable.  They're mainly useful for tweaking performance */
-
-/*! Sets an option on a channel */
-/*!
+/*
+ * Options: Some low-level drivers may implement "options" allowing fine tuning of the
+ * low level channel.  See frame.h for options.  Note that many channel drivers may support
+ * none or a subset of those features, and you should not count on this if you want your
+ * asterisk application to be portable.  They're mainly useful for tweaking performance
+ */
+
+/*!
+ * \brief Sets an option on a channel
+ *
  * \param channel channel to set options on
  * \param option option to change
  * \param data data specific to option
  * \param datalen length of the data
  * \param block blocking or not
+ * \details
  * Set an option on a channel (see frame.h), optionally blocking awaiting the reply
- * Returns 0 on success and -1 on failure
+ * \return 0 on success and -1 on failure
  */
 int ast_channel_setoption(struct ast_channel *channel, int option, void *data, int datalen, int block);
 
@@ -1542,28 +1619,36 @@
 int ast_best_codec(int fmts);
 
 
-/*! Checks the value of an option */
-/*!
+/*!
+ * \brief Checks the value of an option
+ *
  * Query the value of an option
  * Works similarly to setoption except only reads the options.
  */
 int ast_channel_queryoption(struct ast_channel *channel, int option, void *data, int *datalen, int block);
 
-/*! \brief Checks for HTML support on a channel
- * \return 0 if channel does not support HTML or non-zero if it does */
+/*!
+ * \brief Checks for HTML support on a channel
+ * \return 0 if channel does not support HTML or non-zero if it does
+ */
 int ast_channel_supports_html(struct ast_channel *channel);
 
-/*! \brief Sends HTML on given channel
+/*!
+ * \brief Sends HTML on given channel
  * Send HTML or URL on link.
- * \return 0 on success or -1 on failure */
+ * \return 0 on success or -1 on failure
+ */
 int ast_channel_sendhtml(struct ast_channel *channel, int subclass, const char *data, int datalen);
 
-/*! \brief Sends a URL on a given link
+/*!
+ * \brief Sends a URL on a given link
  * Send URL on link.
- * \return 0 on success or -1 on failure */
+ * \return 0 on success or -1 on failure
+ */
 int ast_channel_sendurl(struct ast_channel *channel, const char *url);
 
-/*! \brief Defers DTMF so that you only read things like hangups and audio.
+/*!
+ * \brief Defers DTMF so that you only read things like hangups and audio.
  * \return non-zero if channel was already DTMF-deferred or
  * 0 if channel is just now being DTMF-deferred
  */
@@ -1651,26 +1736,31 @@
  */
 int ast_settimeout(struct ast_channel *c, unsigned int rate, int (*func)(const void *data), void *data);
 
-/*!	\brief Transfer a channel (if supported).  Returns -1 on error, 0 if not supported
-   and 1 if supported and requested
-	\param chan current channel
-	\param dest destination extension for transfer
-*/
+/*!
+ * \brief Transfer a channel (if supported).
+ * \retval -1 on error
+ * \retval 0 if not supported
+ * \retval 1 if supported and requested
+ * \param chan current channel
+ * \param dest destination extension for transfer
+ */
 int ast_transfer(struct ast_channel *chan, char *dest);
 
-/*! \brief  Start masquerading a channel
+/*!
+ * \brief Start masquerading a channel
  * \details
  * XXX This is a seriously whacked out operation.  We're essentially putting the guts of
  *     the clone channel into the original channel.  Start by killing off the original
  *     channel's backend.   I'm not sure we're going to keep this function, because
  *     while the features are nice, the cost is very high in terms of pure nastiness. XXX
- * \param chan  Channel to masquerade
+ * \param chan Channel to masquerade
  */
 int ast_do_masquerade(struct ast_channel *chan);
 
-/*!	\brief Find bridged channel
-	\param chan Current channel
-*/
+/*!
+ * \brief Find bridged channel
+ * \param chan Current channel
+ */
 struct ast_channel *ast_bridged_channel(struct ast_channel *chan);
 
 /*!
@@ -1747,7 +1837,8 @@
 
 /* Misc. functions below */
 
-/*! \brief if fd is a valid descriptor, set *pfd with the descriptor
+/*!
+ * \brief if fd is a valid descriptor, set *pfd with the descriptor
  * \return Return 1 (not -1!) if added, 0 otherwise (so we can add the
  * return value to the index into the array)
  */
@@ -1790,7 +1881,8 @@
 }
 #endif
 
-/*! \brief Waits for activity on a group of channels
+/*!
+ * \brief Waits for activity on a group of channels
  * \param nfds the maximum number of file descriptors in the sets
  * \param rfds file descriptors to check for read availability
  * \param wfds file descriptors to check for write availability
@@ -1853,9 +1945,10 @@
 /*! \brief print call- and pickup groups into buffer */
 char *ast_print_group(char *buf, int buflen, ast_group_t group);
 
-/*! \brief Convert enum channelreloadreason to text string for manager event
+/*!
+ * \brief Convert enum channelreloadreason to text string for manager event
  * \param reason The reason for reload (manager, cli, start etc)
-*/
+ */
 const char *channelreloadreason2txt(enum channelreloadreason reason);
 
 /*! \brief return an ast_variable list of channeltypes */
@@ -1868,8 +1961,7 @@
  */
 const char *ast_channel_reason2str(int reason);
 
-/*! \brief channel group info
- */
+/*! \brief channel group info */
 struct ast_group_info {
 	struct ast_channel *chan;
 	char *category;




More information about the asterisk-commits mailing list