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: https://origsvn.digium.com/svn/asterisk/trunk@185912 65c4cc65-6c06-0410-ace0-fbb531ad65f3

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)

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

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)
 }

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)

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),
 {

main/ast_expr2f.c

@@ -1962,8 +1962,8 @@ YY_BUFFER_STATE ast_yy_scan_string (yyconst char * yystr , yyscan_t yyscanner)
 
 /** Setup the input buffer state to scan the given bytes. The next call to ast_yylex() will
  * scan from a @e copy of @a bytes.
- * @param bytes the byte buffer to scan
- * @param len the number of bytes in the buffer pointed to by @a bytes.
+ * @param yybytes the byte buffer to scan
+ * @param _yybytes_len the number of bytes in the buffer pointed to by @a bytes.
  * @param yyscanner The scanner object.
  * @return the newly allocated buffer state object.
  */
@@ -2124,7 +2124,7 @@ void ast_yyset_lineno (int  line_number , yyscan_t yyscanner)
 }
 
 /** Set the current column.
- * @param line_number
+ * @param column_no
  * @param yyscanner The scanner object.
  */
 void ast_yyset_column (int  column_no , yyscan_t yyscanner)
@@ -2387,19 +2387,12 @@ void ast_yyfree(void *ptr, yyscan_t yyscanner)
 
 int ast_expr(char *expr, char *buf, int length, struct ast_channel *chan)
 {
-	struct parse_io io;
+	struct parse_io io = { .string = expr, .chan = chan };
 	int return_value = 0;
-	
-	memset(&io, 0, sizeof(io));
-	io.string = expr;  /* to pass to the error routine */
-	io.chan = chan;
-	
+
 	ast_yylex_init(&io.scanner);
-	
 	ast_yy_scan_string(expr, io.scanner);
-	
 	ast_yyparse ((void *) &io);
-
 	ast_yylex_destroy(io.scanner);
 
 	if (!io.val) {

main/manager.c

@@ -499,7 +499,7 @@ static struct ast_manager_user *get_manager_by_name_locked(const char *name)
 }
 
 /*! \brief Get displayconnects config option.
- *  \param s manager session to get parameter from.
+ *  \param session manager session to get parameter from.
  *  \return displayconnects config option value.
  */
 static int manager_displayconnects (struct mansession_session *session)

main/strings.c

@@ -66,7 +66,7 @@ int __ast_str_helper(struct ast_str **buf, size_t max_len,
 		}
 		/*
 		 * Ask vsnprintf how much space we need. Remember that vsnprintf
-		 * does not count the final '\0' so we must add 1.
+		 * does not count the final <code>'\0'</code> so we must add 1.
 		 */
 		va_copy(aq, ap);
 		res = vsnprintf((*buf)->__AST_STR_STR + offset, (*buf)->__AST_STR_LEN - offset, fmt, aq);
@@ -156,11 +156,10 @@ char *__ast_str_helper2(struct ast_str **buf, size_t maxlen, const char *src, si
 			ptr += (*buf)->__AST_STR_STR - oldbase;
 		}
 	}
-	if (__builtin_expect(!(maxsrc && maxlen), 0)) {
+	if (__builtin_expect(!maxlen, 0)) {
 		ptr--;
 	}
 	*ptr = '\0';
-	(*buf)->__AST_STR_USED--;
 	return (*buf)->__AST_STR_STR;
 }
 

main/taskprocessor.c

@@ -84,10 +84,10 @@ struct ast_taskprocessor {
 /*! \brief tps_singletons is the astobj2 container for taskprocessor singletons */
 static struct ao2_container *tps_singletons;
 
-/*! \brief CLI 'taskprocessor ping <blah>' operation requires a ping condition */
+/*! \brief CLI <example>taskprocessor ping &lt;blah&gt;</example> operation requires a ping condition */
 static ast_cond_t cli_ping_cond;
 
-/*! \brief CLI 'taskprocessor ping <blah>' operation requires a ping condition lock */
+/*! \brief CLI <example>taskprocessor ping &lt;blah&gt;</example> operation requires a ping condition lock */
 AST_MUTEX_DEFINE_STATIC(cli_ping_cond_lock);
 
 /*! \brief The astobj2 hash callback for taskprocessors */
@@ -101,7 +101,7 @@ static void *tps_processing_function(void *data);
 /*! \brief Destroy the taskprocessor when its refcount reaches zero */
 static void tps_taskprocessor_destroy(void *tps);
 
-/*! \brief CLI 'taskprocessor ping <blah>' handler function */
+/*! \brief CLI <example>taskprocessor ping &lt;blah&gt;</example> handler function */
 static int tps_ping_handler(void *datap);
 
 /*! \brief Remove the front task off the taskprocessor queue */

main/tdd.c

@@ -274,7 +274,9 @@ static inline float tdd_getcarrier(float *cr, float *ci, int bit)
 	PUT_TDD_STOP;	/* Stop bit */ \
 } while(0);	
 
-/*! Generate TDD hold tone */
+/*! Generate TDD hold tone
+ * \param buf Result buffer
+ * \todo How big should this be??? */
 int tdd_gen_holdtone(unsigned char *buf)
 {
 	int bytes = 0;

res/res_odbc.c

@@ -415,11 +415,12 @@ static void destroy_table_cache(struct odbc_cache_tables *table) {
 
 /*!
  * \brief Find or create an entry describing the table specified.
- * \param obj An active ODBC handle on which to query the table
- * \param table Tablename to describe
+ * \param database Name of an ODBC class on which to query the table
+ * \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.
+ * \since 1.6.1
  */
 struct odbc_cache_tables *ast_odbc_find_table(const char *database, const char *tablename)
 {