Merged revisions 185912 via svnmerge from

https://origsvn.digium.com/svn/asterisk/trunk

........
  r185912 | tilghman | 2009-04-01 15:13:28 -0500 (Wed, 01 Apr 2009) | 4 lines
  
  Merge changes from str_substitution that are unrelated to that branch.
  Included is a small bugfix to an ast_str helper, but most of these changes
  are simply doxygen fixes.
........


git-svn-id: http://svn.digium.com/svn/asterisk/branches/1.6.2@185947 f38db490-d61c-443f-a65b-d21fe96a405b

5 files changed, 93 insertions, 53 deletions

diff --git a/include/asterisk.h b/include/asterisk.h
index fdfc1bf60..f159cf375 100644
--- a/include/asterisk.h
+++ b/include/asterisk.h
@@ -146,10 +146,10 @@ char *ast_complete_source_filename(const char *partial, int n);
  *
  * (note, this must be documented a lot more)
  * ast_add_profile allocates a generic 'counter' with a given name,
- * which can be shown with the command 'show profile <name>'
+ * which can be shown with the command 'core show profile &lt;name&gt;'
  *
  * The counter accumulates positive or negative values supplied by
- * ast_add_profile(), dividing them by the 'scale' value passed in the
+ * \see ast_add_profile(), dividing them by the 'scale' value passed in the
  * create call, and also counts the number of 'events'.
  * Values can also be taked by the TSC counter on ia32 architectures,
  * in which case you can mark the start of an event calling ast_mark(id, 1)
diff --git a/include/asterisk/astobj2.h b/include/asterisk/astobj2.h
index c8a464ed7..ee82e5d9b 100644
--- a/include/asterisk/astobj2.h
+++ b/include/asterisk/astobj2.h
@@ -388,6 +388,7 @@ typedef void (*ao2_destructor_fn)(void *);
  *
  * \param data_size The sizeof() of the user-defined structure.
  * \param destructor_fn The destructor function (can be NULL)
+ * \param debug_msg
  * \return A pointer to user-data.
  *
  * Allocates a struct astobj2 with sufficient space for the
@@ -397,23 +398,25 @@ typedef void (*ao2_destructor_fn)(void *);
  * - the refcount of the object just created is 1
  * - the returned pointer cannot be free()'d or realloc()'ed;
  *   rather, we just call ao2_ref(o, -1);
+ *
+ * @{
  */
 
 #ifdef REF_DEBUG
 
 
-#define ao2_t_alloc(arg1, arg2, arg3) _ao2_alloc_debug((arg1), (arg2), (arg3),  __FILE__, __LINE__, __PRETTY_FUNCTION__)
-#define ao2_alloc(arg1, arg2)         _ao2_alloc_debug((arg1), (arg2), "",  __FILE__, __LINE__, __PRETTY_FUNCTION__)
+#define ao2_t_alloc(data_size, destructor_fn, debug_msg) _ao2_alloc_debug((data_size), (destructor_fn), (debug_msg),  __FILE__, __LINE__, __PRETTY_FUNCTION__)
+#define ao2_alloc(data_size, destructor_fn)              _ao2_alloc_debug((data_size), (destructor_fn), "",  __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
 #else
 
-#define ao2_t_alloc(arg1,arg2,arg3) _ao2_alloc((arg1), (arg2))
-#define ao2_alloc(arg1,arg2)        _ao2_alloc((arg1), (arg2))
+#define ao2_t_alloc(data_size, destructor_fn, debug_msg) _ao2_alloc((data_size), (destructor_fn))
+#define ao2_alloc(data_size, destructor_fn)              _ao2_alloc((data_size), (destructor_fn))
 
 #endif
 void *_ao2_alloc_debug(const size_t data_size, ao2_destructor_fn destructor_fn, char *tag, char *file, int line, const char *funcname);
 void *_ao2_alloc(const size_t data_size, ao2_destructor_fn destructor_fn);
-
+/*! @} */
 
 /*! \brief
  * Reference/unreference an object and return the old refcount.
@@ -434,17 +437,20 @@ void *_ao2_alloc(const size_t data_size, ao2_destructor_fn destructor_fn);
  * have a reference count to it, so the only case when the object
  * can go away is when we release our reference, and it is
  * the last one in existence.
+ *
+ * @{
  */
 
 #ifdef REF_DEBUG
-#define ao2_t_ref(arg1,arg2,arg3) _ao2_ref_debug((arg1), (arg2), (arg3),  __FILE__, __LINE__, __PRETTY_FUNCTION__)
-#define ao2_ref(arg1,arg2)        _ao2_ref_debug((arg1), (arg2), "",  __FILE__, __LINE__, __PRETTY_FUNCTION__)
+#define ao2_t_ref(o,delta,tag) _ao2_ref_debug((o), (delta), (tag),  __FILE__, __LINE__, __PRETTY_FUNCTION__)
+#define ao2_ref(o,delta)       _ao2_ref_debug((o), (delta), "",  __FILE__, __LINE__, __PRETTY_FUNCTION__)
 #else
-#define ao2_t_ref(arg1,arg2,arg3) _ao2_ref((arg1), (arg2))
-#define ao2_ref(arg1,arg2)        _ao2_ref((arg1), (arg2))
+#define ao2_t_ref(o,delta,tag) _ao2_ref((o), (delta))
+#define ao2_ref(o,delta)       _ao2_ref((o), (delta))
 #endif
 int _ao2_ref_debug(void *o, int delta, char *tag, char *file, int line, const char *funcname);
 int _ao2_ref(void *o, int delta);
+/*! @} */
 
 /*! \brief
  * Lock an object.
@@ -849,13 +855,15 @@ struct ao2_list {
  *
  * \note When the returned object is no longer in use, ao2_ref() should
  * be used to free the additional reference possibly created by this function.
+ *
+ * @{
  */
 #ifdef REF_DEBUG
-#define ao2_t_callback(arg1,arg2,arg3,arg4,arg5) _ao2_callback_debug((arg1), (arg2), (arg3), (arg4), (arg5), __FILE__, __LINE__, __PRETTY_FUNCTION__)
-#define ao2_callback(arg1,arg2,arg3,arg4)        _ao2_callback_debug((arg1), (arg2), (arg3), (arg4), "", __FILE__, __LINE__, __PRETTY_FUNCTION__)
+#define ao2_t_callback(c,flags,cb_fn,arg,tag) _ao2_callback_debug((c), (flags), (cb_fn), (arg), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
+#define ao2_callback(c,flags,cb_fn,arg)       _ao2_callback_debug((c), (flags), (cb_fn), (arg), "", __FILE__, __LINE__, __PRETTY_FUNCTION__)
 #else
-#define ao2_t_callback(arg1,arg2,arg3,arg4,arg5) _ao2_callback((arg1), (arg2), (arg3), (arg4))
-#define ao2_callback(arg1,arg2,arg3,arg4)        _ao2_callback((arg1), (arg2), (arg3), (arg4))
+#define ao2_t_callback(c,flags,cb_fn,arg,tag) _ao2_callback((c), (flags), (cb_fn), (arg))
+#define ao2_callback(c,flags,cb_fn,arg)       _ao2_callback((c), (flags), (cb_fn), (arg))
 #endif
 void *_ao2_callback_debug(struct ao2_container *c, enum search_flags flags,
 						  ao2_callback_fn *cb_fn, void *arg, char *tag,
@@ -863,6 +871,7 @@ void *_ao2_callback_debug(struct ao2_container *c, enum search_flags flags,
 void *_ao2_callback(struct ao2_container *c,
 					enum search_flags flags,
 					ao2_callback_fn *cb_fn, void *arg);
+/*! @} */
 
 /*! \brief
  * ao2_callback_data() is a generic function that applies cb_fn() to all objects
diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h
index 301edddf3..d3cfb2630 100644
--- a/include/asterisk/pbx.h
+++ b/include/asterisk/pbx.h
@@ -37,12 +37,13 @@ extern "C" {
 #define AST_PBX_KEEP    0
 #define AST_PBX_REPLACE 1
 
-/*! \brief Special return values from applications to the PBX { */
+/*! \brief Special return values from applications to the PBX
+ * @{ */
 #define AST_PBX_HANGUP                -1    /*!< Jump to the 'h' exten */
 #define AST_PBX_OK                     0    /*!< No errors */
 #define AST_PBX_ERROR                  1    /*!< Jump to the 'e' exten */
 #define AST_PBX_INCOMPLETE             12   /*!< Return to PBX matching, allowing more digits for the extension */
-/*! } */
+/*! @} */
 
 #define PRIORITY_HINT	-1	/*!< Special Priority for a hint */
 
@@ -134,7 +135,8 @@ int ast_check_timing(const struct ast_timing *i);
 
 /*!\brief Deallocates memory structures associated with a timing bitmap.
  * \param i Pointer to an ast_timing structure.
- * \retval Returns 0 on success or a number suitable for passing into strerror, otherwise.
+ * \retval 0 success
+ * \retval non-zero failure (number suitable to pass to \see strerror)
  */
 int ast_destroy_timing(struct ast_timing *i);
 
@@ -152,7 +154,8 @@ struct ast_pbx {
  * This function registers a populated ast_switch structure with the
  * asterisk switching architecture.
  *
- * \return 0 on success, and other than 0 on failure
+ * \retval 0 success
+ * \retval non-zero failure
  */
 int ast_register_switch(struct ast_switch *sw);
 
@@ -191,7 +194,8 @@ struct ast_app *pbx_findapp(const char *app);
  * saves the stack and executes the given application passing in
  * the given data.
  *
- * \return 0 on success, and -1 on failure
+ * \retval 0 success
+ * \retval -1 failure
  */
 int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data);
 
@@ -251,7 +255,7 @@ void ast_context_destroy(struct ast_context *con, const char *registrar);
  */
 struct ast_context *ast_context_find(const char *name);
 
-/*! \brief The result codes when starting the PBX on a channelwith \see ast_pbx_start.
+/*! \brief The result codes when starting the PBX on a channel with \see ast_pbx_start.
 	AST_PBX_CALL_LIMIT refers to the maxcalls call limit in asterisk.conf
  */
 enum ast_pbx_result {
@@ -403,18 +407,18 @@ int ast_extension_state_del(int id, ast_state_cb_type callback);
  * \brief If an extension hint exists, return non-zero
  * 
  * \param hint buffer for hint
- * \param maxlen size of hint buffer
+ * \param hintsize size of hint buffer, in bytes
  * \param name buffer for name portion of hint
- * \param maxnamelen size of name buffer
- * \param c this is not important
+ * \param namesize size of name buffer
+ * \param c Channel from which to return the hint.  This is only important when the hint or name contains an expression to be expanded.
  * \param context which context to look in
  * \param exten which extension to search for
  *
  * \return If an extension within the given context with the priority PRIORITY_HINT
- * is found a non zero value will be returned.
+ * is found, a non zero value will be returned.
  * Otherwise, 0 is returned.
  */
-int ast_get_hint(char *hint, int maxlen, char *name, int maxnamelen, 
+int ast_get_hint(char *hint, int hintsize, char *name, int namesize,
 	struct ast_channel *c, const char *context, const char *exten);
 
 /*!
@@ -679,6 +683,8 @@ int ast_context_remove_switch2(struct ast_context *con, const char *sw,
  *
  * \retval 0 on success 
  * \retval -1 on failure
+ *
+ * @{
  */
 int ast_context_remove_extension(const char *context, const char *extension, int priority,
 	const char *registrar);
@@ -692,6 +698,7 @@ int ast_context_remove_extension_callerid(const char *context, const char *exten
 int ast_context_remove_extension_callerid2(struct ast_context *con, const char *extension,
 	int priority, const char *callerid, int matchcid, const char *registrar,
 	int already_locked);
+/*! @} */
 
 /*! 
  * \brief Add an ignorepat
@@ -818,8 +825,13 @@ int ast_context_lockmacro(const char *macrocontext);
  */
 int ast_context_unlockmacro(const char *macrocontext);
 
+/*!\brief Set the channel to next execute the specified dialplan location.
+ * \see ast_async_parseable_goto, ast_async_goto_if_exists
+ */
 int ast_async_goto(struct ast_channel *chan, const char *context, const char *exten, int priority);
 
+/*!\brief Set the channel to next execute the specified dialplan location.
+ */
 int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority);
 
 /*! Synchronously or asynchronously make an outbound call and send it to a
@@ -873,7 +885,8 @@ const char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
 const char *ast_get_switch_registrar(struct ast_sw *sw);
 /*! @} */
 
-/* Walking functions ... */
+/*! @name Walking functions ... */
+/*! @{ */
 struct ast_context *ast_walk_contexts(struct ast_context *con);
 struct ast_exten *ast_walk_context_extensions(struct ast_context *con,
 	struct ast_exten *priority);
@@ -884,13 +897,16 @@ struct ast_include *ast_walk_context_includes(struct ast_context *con,
 struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con,
 	struct ast_ignorepat *ip);
 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
+/*! @} */
 
-/*!
+/*!\brief Create a human-readable string, specifying all variables and their corresponding values.
+ * \param chan Channel from which to read variables
+ * \param buf Dynamic string in which to place the result (should be allocated with \see ast_str_create).
  * \note Will lock the channel.
  */
 int pbx_builtin_serialize_variables(struct ast_channel *chan, struct ast_str **buf);
 
-/*!
+/*!\brief Return a pointer to the value of the corresponding channel variable.
  * \note Will lock the channel.
  *
  * \note This function will return a pointer to the buffer inside the channel
@@ -909,43 +925,51 @@ int pbx_builtin_serialize_variables(struct ast_channel *chan, struct ast_str **b
  */
 const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);
 
-/*!
+/*!\brief Add a variable to the channel variable stack, without removing any previously set value.
  * \note Will lock the channel.
  */
 void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value);
 
-/*!
- * \note Will lock the channel.
+/*!\brief Add a variable to the channel variable stack, removing the most recently set value for the same name.
+ * \note Will lock the channel.  May also be used to set a channel dialplan function to a particular value.
+ * \see ast_func_write
  */
 void pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value);
 
-/*!
+/*!\brief Retrieve the value of a builtin variable or variable from the channel variable stack.
  * \note Will lock the channel.
  */
 void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp);
 void pbx_builtin_clear_globals(void);
 
-/*!
+/*!\brief Parse and set a single channel variable, where the name and value are separated with an '=' character.
  * \note Will lock the channel.
  */
 int pbx_builtin_setvar(struct ast_channel *chan, void *data);
+
+/*!\brief Parse and set multiple channel variables, where the pairs are separated by the ',' character, and name and value are separated with an '=' character.
+ * \note Will lock the channel.
+ */
 int pbx_builtin_setvar_multiple(struct ast_channel *chan, void *data);
 
 int pbx_builtin_raise_exception(struct ast_channel *chan, void *data);
 
-void pbx_substitute_variables_helper(struct ast_channel *c,const char *cp1,char *cp2,int count);
+/*! @name Substitution routines, using static string buffers
+ * @{ */
+void pbx_substitute_variables_helper(struct ast_channel *c, const char *cp1, char *cp2, int count);
 void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count);
 void pbx_substitute_variables_helper_full(struct ast_channel *c, struct varshead *headp, const char *cp1, char *cp2, int cp2_size, size_t *used);
 void ast_str_substitute_variables(struct ast_str **buf, size_t maxlen, struct ast_channel *chan, const char *templ);
+/*! @} */
 
 int ast_extension_patmatch(const char *pattern, const char *data);
 
-/*! Set "autofallthrough" flag, if newval is <0, does not acutally set.  If
+/*! Set "autofallthrough" flag, if newval is <0, does not actually set.  If
   set to 1, sets to auto fall through.  If newval set to 0, sets to no auto
   fall through (reads extension instead).  Returns previous value. */
 int pbx_set_autofallthrough(int newval);
 
-/*! Set "extenpatternmatchnew" flag, if newval is <0, does not acutally set.  If
+/*! Set "extenpatternmatchnew" flag, if newval is <0, does not actually set.  If
   set to 1, sets to use the new Trie-based pattern matcher.  If newval set to 0, sets to use
   the old linear-search algorithm.  Returns previous value. */
 int pbx_set_extenpatternmatchnew(int newval);
@@ -963,10 +987,6 @@ void pbx_set_overrideswitch(const char *newval);
 int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
 
 /*!
- * \note I can find neither parsable nor parseable at dictionary.com, 
- *       but google gives me 169000 hits for parseable and only 49,800 
- *       for parsable 
- *
  * \note This function will handle locking the channel as needed.
  */
 int ast_parseable_goto(struct ast_channel *chan, const char *goto_string);
@@ -1023,7 +1043,8 @@ int ast_processed_calls(void);
  *
  * This application executes a function in read mode on a given channel.
  *
- * \return zero on success, non-zero on failure
+ * \retval 0 success
+ * \retval non-zero failure
  */
 int ast_func_read(struct ast_channel *chan, const char *function, char *workspace, size_t len);
 
@@ -1036,7 +1057,8 @@ int ast_func_read(struct ast_channel *chan, const char *function, char *workspac
  *
  * This application executes a function in write mode on a given channel.
  *
- * \return zero on success, non-zero on failure
+ * \retval 0 success
+ * \retval non-zero failure
  */
 int ast_func_write(struct ast_channel *chan, const char *function, const char *value);
 
@@ -1092,9 +1114,11 @@ struct ast_exten *pbx_find_extension(struct ast_channel *chan,
 int ast_wrlock_contexts_version(void);
 	
 
-/* hashtable functions for contexts */
+/*!\brief hashtable functions for contexts */
+/*! @{ */
 int ast_hashtab_compare_contexts(const void *ah_a, const void *ah_b);
 unsigned int ast_hashtab_hash_contexts(const void *obj);
+/*! @} */
 
 #if defined(__cplusplus) || defined(c_plusplus)
 }
diff --git a/include/asterisk/res_odbc.h b/include/asterisk/res_odbc.h
index 038f2af32..1de1626e8 100644
--- a/include/asterisk/res_odbc.h
+++ b/include/asterisk/res_odbc.h
@@ -35,7 +35,7 @@
 
 typedef enum { ODBC_SUCCESS=0, ODBC_FAIL=-1} odbc_status;
 
-/*! \brief Flags for use with ast_odbc_request_obj2 */
+/*! \brief Flags for use with \see ast_odbc_request_obj2 */
 enum {
 	RES_ODBC_SANITY_CHECK = (1 << 0),
 	RES_ODBC_INDEPENDENT_CONNECTION = (1 << 1),
@@ -102,7 +102,7 @@ int ast_odbc_smart_execute(struct odbc_obj *obj, SQLHSTMT stmt) __attribute__((d
 /*! 
  * \brief Retrieves a connected ODBC object
  * \param name The name of the ODBC class for which a connection is needed.
- * \param check Whether to ensure that a connection is valid before returning the handle.  Usually unnecessary.
+ * \param flags Set of flags used to control which connection is returned.
  * \retval ODBC object 
  * \retval  NULL if there is no connection available with the requested name.
  *
@@ -129,7 +129,7 @@ struct odbc_obj *ast_odbc_request_obj(const char *name, int check);
  * \brief Retrieve a stored ODBC object, if a transaction has been started.
  * \param chan Channel associated with the transaction.
  * \param objname Name of the database handle.  This name corresponds to the name passed
- * to ast_odbc_request_obj2 (or formerly, to ast_odbc_request_obj).  Note that the
+ * to \see ast_odbc_request_obj2 (or formerly, to ast_odbc_request_obj).  Note that the
  * existence of this parameter name explicitly allows for multiple transactions to be open
  * at once, albeit to different databases.
  * \retval A stored ODBC object, if a transaction was already started.
@@ -180,7 +180,7 @@ SQLHSTMT ast_odbc_prepare_and_execute(struct odbc_obj *obj, SQLHSTMT (*prepare_c
 /*!
  * \brief Find or create an entry describing the table specified.
  * \param database Name of an ODBC class on which to query the table
- * \param table Tablename to describe
+ * \param tablename Tablename to describe
  * \retval A structure describing the table layout, or NULL, if the table is not found or another error occurs.
  * When a structure is returned, the contained columns list will be
  * rdlock'ed, to ensure that it will be retained in memory.
@@ -200,7 +200,7 @@ struct odbc_cache_columns *ast_odbc_find_column(struct odbc_cache_tables *table,
 /*!
  * \brief Remove a cache entry from memory
  * \param database Name of an ODBC class (used to ensure like-named tables in different databases are not confused)
- * \param table Tablename for which a cached record should be removed
+ * \param tablename Tablename for which a cached record should be removed
  * \retval 0 if the cache entry was removed, or -1 if no matching entry was found.
  * \since 1.6.1
  */
@@ -213,7 +213,7 @@ int ast_odbc_clear_cache(const char *database, const char *tablename);
 
 /*!\brief Wrapper for SQLGetData to use with dynamic strings
  * \param buf Address of the pointer to the ast_str structure.
- * \param maxlen The maximum size of the resulting string, or 0 for no limit.
+ * \param pmaxlen The maximum size of the resulting string, or 0 for no limit.
  * \param StatementHandle The statement handle from which to retrieve data.
  * \param ColumnNumber Column number (1-based offset) for which to retrieve data.
  * \param TargetType The SQL constant indicating what kind of data is to be retrieved (usually SQL_CHAR)
diff --git a/include/asterisk/strings.h b/include/asterisk/strings.h
index 3e0dd46f0..43ba361f4 100644
--- a/include/asterisk/strings.h
+++ b/include/asterisk/strings.h
@@ -451,7 +451,7 @@ void ast_str_trim_blanks(struct ast_str *buf),
 )
 
 /*!\brief Returns the current length of the string stored within buf.
- * \param A pointer to the ast_str string.
+ * \param buf A pointer to the ast_str structure.
  */
 AST_INLINE_API(
 size_t attribute_pure ast_str_strlen(struct ast_str *buf),
@@ -461,7 +461,8 @@ size_t attribute_pure ast_str_strlen(struct ast_str *buf),
 )
 
 /*!\brief Returns the current maximum length (without reallocation) of the current buffer.
- * \param A pointer to the ast_str string.
+ * \param buf A pointer to the ast_str structure.
+ * \retval Current maximum length of the buffer.
  */
 AST_INLINE_API(
 size_t attribute_pure ast_str_size(struct ast_str *buf),
@@ -471,7 +472,8 @@ size_t attribute_pure ast_str_size(struct ast_str *buf),
 )
 
 /*!\brief Returns the string buffer within the ast_str buf.
- * \param A pointer to the ast_str string.
+ * \param buf A pointer to the ast_str structure.
+ * \retval A pointer to the enclosed string.
  */
 AST_INLINE_API(
 char * attribute_pure ast_str_buffer(struct ast_str *buf),
@@ -480,6 +482,11 @@ char * attribute_pure ast_str_buffer(struct ast_str *buf),
 }
 )
 
+/*!\brief Truncates the enclosed string to the given length.
+ * \param buf A pointer to the ast_str structure.
+ * \param len Maximum length of the string.
+ * \retval A pointer to the resulting string.
+ */
 AST_INLINE_API(
 char *ast_str_truncate(struct ast_str *buf, ssize_t len),
 {