Clean up doxygen warnings

This patch fixes numerous doxygen warnings across Asterisk.  It also updates
the makefile to regenerate the doxygen configuration on the local system
before running doxygen to help prevent warnings/errors on the local system.

Much thanks to Andrew for tackling one of the Asterisk janitor projects!

(issue ASTERISK-20259)
Reported by: Andrew Latham
Patches:
  doxygen_partial.diff uploaded by Andrew Latham (license 5985)
  make_progdocs.diff uploaded by Andrew Latham (license 5985)



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

Makefile

@@ -742,6 +742,7 @@ webvmail:
 	@echo " +-------------------------------------------+"
 
 progdocs:
+	doxygen -u contrib/asterisk-ng-doxygen
 	(cat contrib/asterisk-ng-doxygen; echo "HAVE_DOT=$(HAVEDOT)"; \
 	echo "PROJECT_NUMBER=$(ASTERISKVERSION)") | doxygen -
 

apps/confbridge/include/confbridge.h

@@ -302,10 +302,10 @@ void conf_menu_entry_destroy(struct conf_menu_entry *menu_entry);
  * \brief Once a DTMF sequence matches a sequence in the user's DTMF menu, this function will get
  * called to perform the menu action.
  *
- * \param bridge_channel, Bridged channel this is involving
- * \param conference_bridge_user, the conference user to perform the action on.
- * \param menu_entry, the menu entry that invoked this callback to occur.
- * \param menu, an AO2 referenced pointer to the entire menu structure the menu_entry
+ * \param bridge_channel Bridged channel this is involving
+ * \param conference_bridge_user the conference user to perform the action on.
+ * \param menu_entry the menu entry that invoked this callback to occur.
+ * \param menu an AO2 referenced pointer to the entire menu structure the menu_entry
  *        derived from.
  *
  * \note The menu_entry is a deep copy of the entry found in the menu structure.  This allows

channels/chan_agent.c

@@ -382,7 +382,7 @@ static struct ast_channel_tech agent_tech = {
  * unrefed once it is no longer needed.
  *
  * \param pvt Pointer to the LOCKED agent_pvt for which the owner is needed
- * \ret locked channel which owns the pvt at the time of completion. NULL if not available.
+ * \ref locked channel which owns the pvt at the time of completion. NULL if not available.
  */
 static struct ast_channel *agent_lock_owner(struct agent_pvt *pvt)
 {

channels/chan_sip.c

@@ -5367,7 +5367,7 @@ static struct sip_peer *sip_find_peer_full(const char *peer, struct ast_sockaddr
 
 /*!
  * \brief Locate device by name or ip address
- * \param peer, sin, realtime, devstate_only, transport
+ * \param peer, addr, realtime, devstate_only, transport
  * \param which_objects Define which objects should be matched when doing a lookup
  *        by name.  Valid options are FINDUSERS, FINDPEERS, or FINDALLDEVICES.
  *        Note that this option is not used at all when doing a lookup by IP.
@@ -10965,7 +10965,7 @@ static void add_route(struct sip_request *req, struct sip_route *route)
 /*! \brief Set destination from SIP URI
  *
  * Parse uri to h (host) and port - uri is already just the part inside the <>
- * general form we are expecting is sip[s]:username[:password][;parameter]@host[:port][;...]
+ * general form we are expecting is \verbatim sip[s]:username[:password][;parameter]@host[:port][;...] \endverbatim
  * If there's a port given, turn NAPTR/SRV off. NAPTR might indicate SIPS preference even
  * for SIP: uri's
  *
@@ -15430,8 +15430,14 @@ static void list_route(struct sip_route *route)
 	}
 }
 
-/*! \brief Build route list from Record-Route header 
-    \param resp the SIP response code or 0 for a request */
+/*! \brief Build route list from Record-Route header
+ *
+ * \param p
+ * \param req
+ * \param backwards
+ * \param resp the SIP response code or 0 for a request
+ *
+ */
 static void build_route(struct sip_pvt *p, struct sip_request *req, int backwards, int resp)
 {
 	struct sip_route *thishop, *head, *tail;
@@ -28415,7 +28421,7 @@ enum st_refresher st_get_refresher(struct sip_pvt *p)
 /*!
  * \brief Get the session-timer mode 
  * \param p pointer to the SIP dialog 
- * \param no_cached, set this to true in order to force a peername lookup on
+ * \param no_cached Set this to true in order to force a peername lookup on
  *        the session timer mode.
 */
 enum st_mode st_get_mode(struct sip_pvt *p, int no_cached)
@@ -32260,7 +32266,7 @@ static int reload(void)
 
 /*! \brief  Return the first entry from ast_sockaddr_resolve filtered by address family
  *
- * \warn Using this function probably means you have a faulty design.
+ * \warning Using this function probably means you have a faulty design.
  */
 static int ast_sockaddr_resolve_first_af(struct ast_sockaddr *addr,
 				      const char* name, int flag, int family)
@@ -32284,7 +32290,7 @@ static int ast_sockaddr_resolve_first_af(struct ast_sockaddr *addr,
 
 /*! \brief  Return the first entry from ast_sockaddr_resolve filtered by family of binddaddr
  *
- * \warn Using this function probably means you have a faulty design.
+ * \warning Using this function probably means you have a faulty design.
  */
 static int ast_sockaddr_resolve_first(struct ast_sockaddr *addr,
 				      const char* name, int flag)
@@ -32294,7 +32300,7 @@ static int ast_sockaddr_resolve_first(struct ast_sockaddr *addr,
 
 /*! \brief  Return the first entry from ast_sockaddr_resolve filtered by family of binddaddr
  *
- * \warn Using this function probably means you have a faulty design.
+ * \warning Using this function probably means you have a faulty design.
  */
 static int ast_sockaddr_resolve_first_transport(struct ast_sockaddr *addr,
 						const char* name, int flag, unsigned int transport)

channels/sig_pri.h

@@ -592,7 +592,7 @@ struct sig_pri_span {
 	 * AST_DEVICE_BUSY - All B channels are in use.
 	 * AST_DEVICE_UNAVAILABLE - Span is in alarm.
 	 * \note
-	 * Device name: \startverbatim DAHDI/I<span>/congestion. \endverbatim
+	 * Device name: \verbatim DAHDI/I<span>/congestion. \endverbatim
 	 */
 	int congestion_devstate;
 #if defined(THRESHOLD_DEVSTATE_PLACEHOLDER)

channels/sip/include/srtp.h

@@ -16,7 +16,7 @@
  * at the top of the source tree.
  */
 
-/*! \file sip_srtp.h
+/*! \file srtp.h
  *
  * \brief SIP Secure RTP (SRTP)
  *

channels/sip/srtp.c

@@ -16,7 +16,7 @@
  * at the top of the source tree.
  */
 
-/*! \file sip_srtp.c
+/*! \file srtp.c
  *
  * \brief SIP Secure RTP (SRTP)
  *

codecs/speex/speex_resampler.h

@@ -137,7 +137,8 @@ SpeexResamplerState *speex_resampler_init(spx_uint32_t nb_channels,
  * @param in_rate Input sampling rate rounded to the nearest integer (in Hz).
  * @param out_rate Output sampling rate rounded to the nearest integer (in Hz).
  * @param quality Resampling quality between 0 and 10, where 0 has poor quality
- * and 10 has very high quality.
+ * 	and 10 has very high quality.
+ * @param err
  * @return Newly created resampler state
  * @retval NULL Error: not enough memory
  */

formats/format_ogg_vorbis.c

@@ -342,7 +342,7 @@ static struct ast_frame *ogg_vorbis_read(struct ast_filestream *fs,
 
 /*!
  * \brief Trucate an OGG/Vorbis filestream.
- * \param s The filestream to truncate.
+ * \param fs The filestream to truncate.
  * \return 0 on success, -1 on failure.
  */
 
@@ -354,7 +354,7 @@ static int ogg_vorbis_trunc(struct ast_filestream *fs)
 
 /*!
  * \brief Tell the current position in OGG/Vorbis filestream measured in pcms.
- * \param s The filestream to take action on.
+ * \param fs The filestream to take action on.
  * \return 0 or greater with the position measured in samples, or -1 for false.
  */
 static off_t ogg_vorbis_tell(struct ast_filestream *fs)
@@ -374,7 +374,7 @@ static off_t ogg_vorbis_tell(struct ast_filestream *fs)
 
 /*!
  * \brief Seek to a specific position in an OGG/Vorbis filestream.
- * \param s The filestream to take action on.
+ * \param fs The filestream to take action on.
  * \param sample_offset New position for the filestream, measured in 8KHz samples.
  * \param whence Location to measure 
  * \return 0 on success, -1 on failure.

include/asterisk/astobj2.h

@@ -522,6 +522,7 @@ enum ao2_lock_req {
  * Lock an object.
  *
  * \param a A pointer to the object we want to lock.
+ * \param lock_how, file, func, line, var
  * \return 0 on success, other values on error.
  */
 int __ao2_lock(void *a, enum ao2_lock_req lock_how, const char *file, const char *func, int line, const char *var);
@@ -533,6 +534,7 @@ int __ao2_lock(void *a, enum ao2_lock_req lock_how, const char *file, const char
  * Unlock an object.
  *
  * \param a A pointer to the object we want unlock.
+ * \param file, func, line, var
  * \return 0 on success, other values on error.
  */
 int __ao2_unlock(void *a, const char *file, const char *func, int line, const char *var);
@@ -542,6 +544,7 @@ int __ao2_unlock(void *a, const char *file, const char *func, int line, const ch
  * Try locking-- (don't block if fail)
  *
  * \param a A pointer to the object we want to lock.
+ * \param lock_how, file, func, line, var
  * \return 0 on success, other values on error.
  */
 int __ao2_trylock(void *a, enum ao2_lock_req lock_how, const char *file, const char *func, int line, const char *var);
@@ -1044,7 +1047,6 @@ struct ao2_container *__ao2_container_clone_debug(struct ao2_container *orig, en
  *
  * \param container The container to operate on.
  * \param obj The object to be added.
- * \param flags search_flags to control linking the object.  (OBJ_NOLOCK)
  * \param tag used for debugging.
  *
  * \retval NULL on errors.
@@ -1062,6 +1064,24 @@ struct ao2_container *__ao2_container_clone_debug(struct ao2_container *orig, en
 #define ao2_t_link(container, obj, tag)					__ao2_link_debug((container), (obj), 0, (tag),  __FILE__, __LINE__, __PRETTY_FUNCTION__)
 #define ao2_link(container, obj)						__ao2_link_debug((container), (obj), 0, "",  __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
+/*!
+ * \brief Add an object to a container.
+ *
+ * \param container The container to operate on.
+ * \param obj The object to be added.
+ * \param flags search_flags to control linking the object.  (OBJ_NOLOCK)
+ * \param tag used for debugging.
+ *
+ * \retval NULL on errors.
+ * \retval !NULL on success.
+ *
+ * This function inserts an object in a container according its key.
+ *
+ * \note Remember to set the key before calling this function.
+ *
+ * \note This function automatically increases the reference count to account
+ *       for the reference that the container now holds to the object.
+ */
 #define ao2_t_link_flags(container, obj, flags, tag)	__ao2_link_debug((container), (obj), (flags), (tag),  __FILE__, __LINE__, __PRETTY_FUNCTION__)
 #define ao2_link_flags(container, obj, flags)			__ao2_link_debug((container), (obj), (flags), "",  __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
@@ -1083,7 +1103,6 @@ void *__ao2_link(struct ao2_container *c, void *obj_new, int flags);
  *
  * \param container The container to operate on.
  * \param obj The object to unlink.
- * \param flags search_flags to control unlinking the object.  (OBJ_NOLOCK)
  * \param tag used for debugging.
  *
  * \retval NULL, always
@@ -1101,6 +1120,25 @@ void *__ao2_link(struct ao2_container *c, void *obj_new, int flags);
 #define ao2_t_unlink(container, obj, tag)				__ao2_unlink_debug((container), (obj), 0, (tag),  __FILE__, __LINE__, __PRETTY_FUNCTION__)
 #define ao2_unlink(container, obj)						__ao2_unlink_debug((container), (obj), 0, "",  __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
+/*!
+ * \brief Remove an object from a container
+ *
+ * \param container The container to operate on.
+ * \param obj The object to unlink.
+ * \param flags search_flags to control unlinking the object.  (OBJ_NOLOCK)
+ * \param tag used for debugging.
+ *
+ * \retval NULL, always
+ *
+ * \note The object requested to be unlinked must be valid.  However, if it turns
+ *       out that it is not in the container, this function is still safe to
+ *       be called.
+ *
+ * \note If the object gets unlinked from the container, the container's
+ *       reference to the object will be automatically released. (The
+ *       refcount will be decremented).
+ */
+
 #define ao2_t_unlink_flags(container, obj, flags, tag)	__ao2_unlink_debug((container), (obj), (flags), (tag),  __FILE__, __LINE__, __PRETTY_FUNCTION__)
 #define ao2_unlink_flags(container, obj, flags)			__ao2_unlink_debug((container), (obj), (flags), "",  __FILE__, __LINE__, __PRETTY_FUNCTION__)
 

include/asterisk/audiohook.h

@@ -154,10 +154,10 @@ struct ast_frame *ast_audiohook_read_frame(struct ast_audiohook *audiohook, size
 /*! \brief Reads a frame in from the audiohook structure in mixed audio mode and copies read and write frame data to provided arguments.
  * \param audiohook Audiohook structure
  * \param samples Number of samples wanted
- * \param direction Direction the audio frame came from
- * \param format Format of frame remote side wants back
- * \param ast_frame read_frame - if available, we'll copy the read buffer to this.
- * \param ast_frame write_frame - if available, we'll copy the write buffer to this.
+ * \param ast_format Format of frame remote side wants back
+ * \param read_frame if available, we'll copy the read buffer to this.
+ * \param write_frame if available, we'll copy the write buffer to this.
+ * \param direction
  * \return Returns frame on success, NULL on failure
  */
 struct ast_frame *ast_audiohook_read_frame_all(struct ast_audiohook *audiohook, size_t samples, struct ast_format *format, struct ast_frame **read_frame, struct ast_frame **write_frame);

include/asterisk/bridging.h

@@ -312,7 +312,7 @@ int ast_bridge_destroy(struct ast_bridge *bridge);
  * \param chan Channel to join
  * \param swap Channel to swap out if swapping
  * \param features Bridge features structure
- * \param (Optional) Bridging tech optimization parameters for this channel.
+ * \param tech_args Optional Bridging tech optimization parameters for this channel.
  *
  * \retval state that channel exited the bridge with
  *
@@ -504,8 +504,8 @@ void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast
 /*! \brief Adjust the internal mixing sample rate of a bridge used during
  *         multimix mode.
  *
- * \param bridge_channel Channel to change the sample rate on.
- * \param sample rate, the sample rate to change to. If a
+ * \param bridge Channel to change the sample rate on.
+ * \param sample_rate the sample rate to change to. If a
  *        value of 0 is passed here, the bridge will be free to pick
  *        what ever sample rate it chooses.
  *
@@ -515,8 +515,8 @@ void ast_bridge_set_internal_sample_rate(struct ast_bridge *bridge, unsigned int
 /*! \brief Adjust the internal mixing interval of a bridge used during
  *         multimix mode.
  *
- * \param bridge_channel Channel to change the sample rate on.
- * \param mixing_interval, the sample rate to change to.  If 0 is set
+ * \param bridge Channel to change the sample rate on.
+ * \param mixing_interval the sample rate to change to.  If 0 is set
  * the bridge tech is free to choose any mixing interval it uses by default.
  */
 void ast_bridge_set_mixing_interval(struct ast_bridge *bridge, unsigned int mixing_interval);

include/asterisk/bridging_technology.h

@@ -153,7 +153,7 @@ void ast_bridge_handle_trip(struct ast_bridge *bridge, struct ast_bridge_channel
  *
  * \param bridge The bridge that the channel is a part of.
  * \param bridge_channel The bridge channel that has either started or stopped talking.
- * \param started_talking, set to 1 when this indicates the channel has started talking, set to 0
+ * \param started_talking set to 1 when this indicates the channel has started talking set to 0
  * when this indicates the channel has stopped talking.
  */
 void ast_bridge_notify_talking(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, int started_talking);

include/asterisk/ccss.h

@@ -1365,8 +1365,8 @@ int ast_cc_monitor_count(const char * const name, const char * const type);
  * The code in the core will take care of making sure that the information gets passed
  * up the ladder correctly.
  *
- * \param core_id The core ID of the corresponding CC transaction
- * \param debug
+ * \par core_id The core ID of the corresponding CC transaction
+ * \par debug
  * \retval 0 Request successfully queued
  * \retval -1 Request could not be queued
  */
@@ -1482,7 +1482,7 @@ int ast_cc_agent_set_interfaces_chanvar(struct ast_channel *chan);
 /*!
  * \since 1.8
  * \brief Set the CC_INTERFACES channel variable for a channel using an
- * extension@context as a starting point
+ * \verbatim extension@context \endverbatim as a starting point
  *
  * \details
  * The CC_INTERFACES channel variable will have the interfaces that should be
@@ -1498,7 +1498,7 @@ int ast_cc_agent_set_interfaces_chanvar(struct ast_channel *chan);
  *
  * \param chan The channel to set the CC_INTERFACES variable on
  * \param extension The name of the extension for which we're setting the variable.
- * This should be in the form of "exten@context"
+ * This should be in the form of \verbatim exten@context \endverbatim
  */
 int ast_set_cc_interfaces_chanvar(struct ast_channel *chan, const char * const extension);
 

include/asterisk/channel.h

@@ -1280,7 +1280,7 @@ struct ast_channel *ast_request(const char *type, struct ast_format_cap *request
  *        by the low level module and attempt to place a call on it
  *
  * \param type type of channel to request
- * \param format capabilities for requested channel
+ * \param cap format capabilities for requested channel
  * \param requestor channel asking for data
  * \param addr destination of the call
  * \param timeout maximum amount of time to wait for an answer
@@ -1298,7 +1298,7 @@ struct ast_channel *ast_request_and_dial(const char *type, struct ast_format_cap
  * \brief Request a channel of a given type, with data as optional information used
  * by the low level module and attempt to place a call on it
  * \param type type of channel to request
- * \param format capabilities for requested channel
+ * \param cap format capabilities for requested channel
  * \param requestor channel requesting data
  * \param addr destination of the call
  * \param timeout maximum amount of time to wait for an answer
@@ -1317,7 +1317,7 @@ struct ast_channel *__ast_request_and_dial(const char *type, struct ast_format_c
  * \param caller in channel that requested orig
  * \param orig channel being replaced by the call forward channel
  * \param timeout maximum amount of time to wait for setup of new forward channel
- * \param format capabilities for requested channel
+ * \param cap format capabilities for requested channel
  * \param oh outgoing helper used with original channel
  * \param outstate reason why unsuccessful (if uncuccessful)
  * \return Returns the forwarded call's ast_channel on success or NULL on failure
@@ -1794,7 +1794,7 @@ int ast_set_read_format_from_cap(struct ast_channel *chan, struct ast_format_cap
 /*!
  * \brief Sets read format on channel chan
  * \param chan channel to change
- * \param formats, format to set for reading
+ * \param format format to set for reading
  * \return Returns 0 on success, -1 on failure
  */
 int ast_set_read_format(struct ast_channel *chan, struct ast_format *format);
@@ -1802,7 +1802,7 @@ int ast_set_read_format(struct ast_channel *chan, struct ast_format *format);
 /*!
  * \brief Sets read format on channel chan by id
  * \param chan channel to change
- * \param format id to set for reading, only used for formats without attributes
+ * \param id format id to set for reading, only used for formats without attributes
  * \return Returns 0 on success, -1 on failure
  */
 int ast_set_read_format_by_id(struct ast_channel *chan, enum ast_format_id id);
@@ -1819,7 +1819,7 @@ int ast_set_write_format_from_cap(struct ast_channel *chan, struct ast_format_ca
 /*!
  * \brief Sets write format on channel chan
  * \param chan channel to change
- * \param formats, format to set for writing
+ * \param format format to set for writing
  * \return Returns 0 on success, -1 on failure
  */
 int ast_set_write_format(struct ast_channel *chan, struct ast_format *format);
@@ -1827,7 +1827,7 @@ int ast_set_write_format(struct ast_channel *chan, struct ast_format *format);
 /*!
  * \brief Sets write format on channel chan
  * \param chan channel to change
- * \param format id to set for writing, only used for formats without attributes
+ * \param id format id to set for writing, only used for formats without attributes
  * \return Returns 0 on success, -1 on failure
  */
 int ast_set_write_format_by_id(struct ast_channel *chan, enum ast_format_id id);
@@ -2100,7 +2100,7 @@ int ast_channel_setoption(struct ast_channel *channel, int option, void *data, i
 /*!
  * \brief Pick the best codec
  *
- * \param capabilities to pick best codec out of
+ * \param cap capabilities to pick best codec out of
  * \param result stucture to store the best codec in.
  * \retval on success, pointer to result structure
  * \retval on failure, NULL

include/asterisk/config.h

@@ -193,7 +193,7 @@ struct ast_variable *ast_category_root(struct ast_config *config, char *cat);
  * \brief Sorts categories in a config in the order of a numerical value contained within them.
  *
  * \param config The config structure you wish to sort
- * \param variable Which numerical value you wish to sort by
+ * \param comparator variable Which numerical value you wish to sort by
  * \param descending If true, we sort highest to lowest instead of lowest to highest
  *
  * \details
@@ -741,9 +741,9 @@ enum ast_parse_flags {
  *
  * \param arg the string to parse. It is not modified.
  * \param flags combination of ast_parse_flags to specify the
- * return type and additional checks.
+ * 	return type and additional checks.
  * \param result pointer to the result. NULL is valid here, and can
- * be used to perform only the validity checks.
+ * 	be used to perform only the validity checks.
  * \param ... extra arguments are required according to flags.
  *
  * \retval 0 in case of success, != 0 otherwise.
@@ -841,7 +841,7 @@ int ast_rq_is_int(require_type type),
  * \param chunk Data to be decoded
  * \return The decoded data, in the original buffer
  * \since 1.8
- * \warn This function modifies the original buffer
+ * \warning This function modifies the original buffer
  */
 char *ast_realtime_decode_chunk(char *chunk);
 

include/asterisk/config_options.h

@@ -176,7 +176,6 @@ void *aco_pending_config(struct aco_info *info);
 /*! \def CONFIG_INFO_STANDARD
  * \brief Declare an aco_info struct with default module and preload values
  * \param name The name of the struct
- * \param fn The filename of the config
  * \param arr The global object array for holding the user-defined config object
  * \param alloc The allocater for the user-defined config object
  *
@@ -462,7 +461,6 @@ enum aco_process_status aco_process_config(struct aco_info *info, int reload);
  * \param info The aco_info to be used for handling the config
  * \param file The file attached to aco_info that the config represents
  * \param cfg A pointer to a loaded ast_config to parse
- * \param reload Whether or not this is a reload
  *
  * \retval ACO_PROCESS_OK Success
  * \retval ACO_PROCESS_ERROR Failure
@@ -496,7 +494,7 @@ int aco_process_var(struct aco_type *type, const char *cat, struct ast_variable
 int aco_process_category_options(struct aco_type *type, struct ast_config *cfg, const char *cat, void *obj);
 
 /*! \brief Set all default options of \a obj
- * \param info The aco_type with the options
+ * \param type The aco_type with the options
  * \param category The configuration category from which \a obj is being configured
  * \param obj The object being configured
  *
@@ -511,11 +509,12 @@ int aco_set_defaults(struct aco_type *type, const char *category, void *obj);
  *
  * \param info The aco_info holding this module's config information
  * \param name The name of the option
+ * \param match_type
  * \param types An array of valid option types for matching categories to the correct struct type
  * \param default_val The default value of the option in the same format as defined in a config file
  * \param type The option type (only for default handlers)
  * \param handler The handler function for the option (only for non-default types)
- * \param flags \a type specific flags, stored in the option and available to the handler
+ * \param flags a type specific flags, stored in the option and available to the handler
  * \param argc The number for variadic arguments
  * \param ... field offsets to store for default handlers
  *
@@ -528,10 +527,12 @@ int __aco_option_register(struct aco_info *info, const char *name, enum aco_matc
 /*! \brief Register a config option
  * \param info A pointer to the aco_info struct
  * \param name The name of the option
+ * \param matchtype
  * \param types An array of valid option types for matching categories to the correct struct type
  * \param default_val The default value of the option in the same format as defined in a config file
  * \param opt_type The option type for default option type handling
- * \param flags \a type specific flags, stored in the option and available to the handler
+ * \param flags a type specific flags, stored in the option and available to the handler
+ * \param ...
  *
  * \retval 0 Success
  * \retval -1 Failure
@@ -542,6 +543,7 @@ int __aco_option_register(struct aco_info *info, const char *name, enum aco_matc
 /*! \brief Register a config option
  * \param info A pointer to the aco_info struct
  * \param name The name of the option
+ * \param matchtype
  * \param types An array of valid option types for matching categories to the correct struct type
  * \param default_val The default value of the option in the same format as defined in a config file
  * \param handler The handler callback for the option
@@ -570,14 +572,15 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru
  * passed in. It is currently limited to 8 arguments, but 8 variadic
  * arguments, like 640K, should be good enough for anyone. If not, it is
  * easy to add more.
- * */
+ *
+ */
 
-/*! \def ARGMAP(func, func_arg, x, ...)
+/*!
  * \brief Map \a func(\a func_arg, field) across all fields including \a x
  * \param func The function (almost certainly offsetof) to map across the fields
  * \param func_arg The first argument (almost certainly a type (e.g. "struct mystruct")
  * \param x The first field
- * \param varargs The rest of the fields
+ * \param ... varargs The rest of the fields
  *
  * Example usage:
  * \code
@@ -588,17 +591,19 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru
  * };
  * ARGMAP(offsetof, struct foo, a, c)
  * \endcode
+ *
  * produces the string:
+ *
  * \code
  * 2, offsetof(struct foo, a), offsetof(struct foo, b)
- * \encode
+ * \endcode
  * which can be passed as the varargs to some other function
  *
  * The macro isn't limited to offsetof, but that is the only purpose for
  * which it has been tested.
  *
  * As an example of how the processing works:
- *
+ * \verbatim
  * ARGMAP(offsetof, struct foo, a, b, c) ->
  * ARGMAP_(3, offsetof, struct foo, a, b, c) ->
  * ARGMAP_3(offsetof, struct foo, 3, a, b, c) ->
@@ -606,12 +611,15 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru
  * ARGMAP_1(offsetof, struct foo, ARGIFY(3, offsetof(struct foo, a), offsetof(struct foo, b)), c) ->
  * ARGIFY(3, offsetof(struct foo, a), offsetof(struct foo, b), offsetof(struct foo, c)) ->
  * 3, offsetof(struct foo, a), offsetof(struct foo, b), offsetof(struct foo, c)
+ * \endverbatim
+ *
  */
 #define ARGMAP(func, func_arg, x, ...) ARGMAP_(VA_NARGS(x, ##__VA_ARGS__), func, func_arg, x, __VA_ARGS__)
 
 /*! \note This is sneaky. On the very first argument, we set "in" to N, the number of arguments, so
  * that the accumulation both works properly for the first argument (since "in" can't be empty) and
- * we get the number of arguments in our varargs as a bonus */
+ * we get the number of arguments in our varargs as a bonus
+ */
 #define ARGMAP_(N, func, func_arg, x, ...) PASTE(ARGMAP_, N)(func, func_arg, N, x, __VA_ARGS__)
 
 /*! \def PASTE(arg1, arg2)
@@ -629,7 +637,7 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru
  * \param func_arg The first argument to func (most likely a type e.g. "struct my_struct")
  * \param in The accumulated function-mapped field names so far
  * \param x The next field name
- * \param varargs The rest of the field names
+ * \param ... varargs The rest of the field names
  */
 #define ARGMAP_1(func, func_arg, in, x, ...) ARGIFY(in, func(func_arg, x))
 #define ARGMAP_2(func, func_arg, in, x, ...)\
@@ -651,18 +659,19 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru
  * \brief Results in the number of arguments passed to it
  * \note Currently only up to 8, but expanding is easy. This macro basically counts
  * commas + 1. To visualize:
- *
+ * \verbatim
  * VA_NARGS(one, two, three) ->                    v
  * VA_NARGS1(one, two, three,  8,  7,  6,  5,  4,  3,  2,  1,  0) ->
  * VA_NARGS1( _1,  _2,    _3, _4, _5, _6, _7, _8,  N, ...       ) N -> 3
- *
+ * 
  * Note that VA_NARGS *does not* work when there are no arguments passed. Pasting an empty
  * __VA_ARGS__ with a comma like ", ##__VA_ARGS__" will delete the leading comma, but it
  * does not work when __VA_ARGS__ is the first argument. Instead, 1 is returned instead of 0:
- *
+ * 
  * VA_NARGS() ->                              v
  * VA_NARGS1(  ,  8,  7,  6,  5,  4,  3,  2,  1,  0) ->
  * VA_NARGS1(_1, _2, _3, _4, _5, _6, _7, _8,  N) -> 1
+ * \endverbatim
  */
 #define VA_NARGS(...) VA_NARGS1(__VA_ARGS__, 8, 7, 6, 5, 4, 3, 2, 1, 0)
 #define VA_NARGS1(_1, _2, _3, _4, _5, _6, _7, _8, N, ...) N
@@ -670,7 +679,7 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru
 /*! \def FLDSET(type, ...)
  * \brief Convert a struct and list of fields to an argument list of field offsets
  * \param type The type with the fields (e.g. "struct my_struct")
- * \param varags The fields in the struct whose offsets are needed as arguments
+ * \param ... varags The fields in the struct whose offsets are needed as arguments
  *
  * For example:
  * \code
@@ -692,7 +701,7 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru
  * default stringfield option handler, so registering options that point to stringfields requires
  * this macro to be called instead of the FLDSET macro.
  * \param type The type with the fields (e.g. "struct my_struct")
- * \param varargs The fields in the struct whose offsets are needed as arguments
+ * \param ... varargs The fields in the struct whose offsets are needed as arguments
  */
 #define STRFLDSET(type, ...) FLDSET(type, __VA_ARGS__, __field_mgr_pool, __field_mgr)
 
@@ -710,9 +719,10 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru
  * FLDSET. This is because a call to FLDSET may be followed by additional arguments in
  * aco_register_option, so the true number of arguments will possibly be different than what
  * ARGMAP returns.
- * \params varags A list of arguments
- *
+ * \param ... varags A list of arguments
+ * \verbatim
  * POPPED(a, b, c) -> b, c
+ * \endverbatim
  */
 #define POPPED(...) POPPED1(__VA_ARGS__)
 #define POPPED1(x, ...) __VA_ARGS__

include/asterisk/crypto.h

@@ -46,8 +46,8 @@ struct ast_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)
+ * \param key Name of the key we are retrieving
+ * \param type Intger type of key (AST_KEY_PUBLIC or AST_KEY_PRIVATE)
  *
  * \retval the key on success.
  * \retval NULL on failure.
@@ -70,6 +70,7 @@ AST_OPTIONAL_API(int, ast_check_signature, (struct ast_key *key, const char *msg
  * \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 msglen
  * \param sig the proposed valid signature in raw binary representation
  *
  * \retval 0 if the signature is valid.
@@ -95,6 +96,7 @@ AST_OPTIONAL_API(int, ast_sign, (struct ast_key *key, char *msg, char *sig), { r
  * \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 msglen
  * \param sig a pointer to a buffer of at least 128 bytes in which the
  * raw encoded signature will be stored
  *

include/asterisk/datastore.h

@@ -63,6 +63,7 @@ struct ast_datastore {
  * \brief Create a data store object
  * \param[in] info information describing the data store object
  * \param[in] uid unique identifer
+ * \param file, line, function
  * \version 1.6.1 moved here and renamed from ast_channel_datastore_alloc
  */
 struct ast_datastore * attribute_malloc __ast_datastore_alloc(const struct ast_datastore_info *info, const char *uid,

include/asterisk/format.h

@@ -264,9 +264,9 @@ void ast_format_sdp_generate(const struct ast_format *format, unsigned int paylo
  * with optional format attributes represented by format specific key value pairs.
  *
  * \param format to set
- * \param id, format id to set on format
+ * \param id format id to set on format
  * \param set_attributes, are there attributes to set on this format. 0 == false, 1 == True.
- * \param var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END;
+ * \param ... var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END;
  *
  * \details Example usage.
  * ast_format_set(format, AST_FORMAT_ULAW, 0); // no capability attributes are needed for ULAW
@@ -290,7 +290,7 @@ struct ast_format *ast_format_set(struct ast_format *format, enum ast_format_id
  * set additional format attributes to the structure.
  *
  * \param format to set
- * \param var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END;
+ * \param ... var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END;
  *
  * \details Example usage.
  * ast_format_set(format, AST_FORMAT_SILK, 0);
@@ -421,7 +421,7 @@ const char* ast_getformatname(const struct ast_format *format);
 /*! \brief Returns a string containing all formats pertaining to an format id.
  * \param buf a buffer for the output string
  * \param size size of buf (bytes)
- * \param format id.
+ * \param id format id.
  * \return The return value is buf.
  */
 char* ast_getformatname_multiple_byid(char *buf, size_t size, enum ast_format_id id);

include/asterisk/format_cap.h

@@ -119,7 +119,7 @@ int ast_format_cap_is_empty(const struct ast_format_cap *cap);
 /*!
  * \brief Remove format capability from capability structure.
  *
- * \Note format must match Exactly to format in ast_format_cap object in order
+ * \note format must match Exactly to format in ast_format_cap object in order
  * to be removed.
  *
  * \retval 0, remove was successful
@@ -131,7 +131,7 @@ int ast_format_cap_remove(struct ast_format_cap *cap, struct ast_format *format)
  * \brief Remove all format capabilities from capability
  * structure for a specific format id.
  *
- * \Note This will remove _ALL_ formats matching the format id from the
+ * \note This will remove _ALL_ formats matching the format id from the
  * capabilities structure.
  *
  * \retval 0, remove was successful
@@ -263,7 +263,7 @@ void ast_format_cap_iter_start(struct ast_format_cap *cap);
  * }
  * ast_format_cap_iter_end(Cap);
  *
- * \Note Unless the container was alloced using no_lock, the container
+ * \note Unless the container was alloced using no_lock, the container
  * will be locked during the entire iteration until ast_format_cap_iter_end
  * is called. XXX Remember this, and do not attempt to lock any containers
  * within this iteration that will violate locking order.
@@ -298,7 +298,7 @@ void ast_format_cap_from_old_bitfield(struct ast_format_cap *dst, uint64_t src);
 /*! \brief Get the names of a set of formats
  * \param buf a buffer for the output string
  * \param size size of buf (bytes)
- * \param format the format (combined IDs of codecs)
+ * \param cap format the format (combined IDs of codecs)
  * Prints a list of readable codec names corresponding to "format".
  * ex: for format=AST_FORMAT_GSM|AST_FORMAT_SPEEX|AST_FORMAT_ILBC it will return "0x602 (GSM|SPEEX|ILBC)"
  * \return The return value is buf.

include/asterisk/format_pref.h

@@ -59,9 +59,9 @@ void ast_codec_pref_init(struct ast_codec_pref *pref);
 
 /*!
  * \brief Codec located at a particular place in the preference index.
- * \param preference structure to get the codec out of
+ * \param pref preference structure to get the codec out of
  * \param index to retrieve from
- * \param retult ast_format structure to store the index value in
+ * \param result ast_format structure to store the index value in
  * \return pointer to input ast_format on success, NULL on failure
 */
 struct ast_format *ast_codec_pref_index(struct ast_codec_pref *pref, int index, struct ast_format *result);

include/asterisk/framehook.h

@@ -219,9 +219,9 @@ struct ast_framehook_interface {
  * \brief Attach an framehook onto a channel for frame interception.
  * \since 1.8
  *
- * \param ast_channel, The channel to attach the hook on to.
- * \param framehook interface, The framehook's callback functions and stored data.
-*
+ * \param chan ast_channel The channel to attach the hook on to.
+ * \param i framehook interface, The framehook's callback functions and stored data.
+ *
  * \pre XXX The Channel must be locked during this function all.
  *
  * \note The data pointer is never touched by the framehook API except to
@@ -242,8 +242,8 @@ int ast_framehook_attach(struct ast_channel *chan, struct ast_framehook_interfac
  * the framehook will be detached and destroyed during channel
  * destruction.
  *
- * \param The channel the framehook is attached to
- * \param The framehook's id
+ * \param chan The channel the framehook is attached to
+ * \param framehook_id The framehook's id
  *
  * \retval 0 success
  * \retval -1 framehook did not exist on the channel. This means the
@@ -258,7 +258,7 @@ int ast_framehook_detach(struct ast_channel *chan, int framehook_id);
  *
  * \pre XXX The Channel must be locked during this function all.
  * 
- * \param channel containing the framehook list to destroy.
+ * \param chan channel containing the framehook list to destroy.
  * \retval 0 success
  * \retval -1 failure
  */
@@ -274,7 +274,7 @@ int ast_framehook_list_destroy(struct ast_channel *chan);
  *
  * \pre XXX The Channel must be locked during this function all.
  *
- * \param framehook list to push event to.
+ * \param framehooks list to push event to.
  * \param frame being pushed to the framehook list.
  *
  * \return The resulting frame after being viewed and modified by the framehook callbacks.
@@ -291,7 +291,7 @@ struct ast_frame *ast_framehook_list_read_event(struct ast_framehook_list *frame
  *
  * \pre XXX The Channel must be locked during this function all.
  *
- * \param framehook list to push event to.
+ * \param framehooks list to push event to.
  * \param frame being pushed to the framehook list.
  *
  * \return The resulting frame after being viewed and modified by the framehook callbacks.
@@ -303,7 +303,7 @@ struct ast_frame *ast_framehook_list_write_event(struct ast_framehook_list *fram
  * \since 1.8
  * \pre XXX The Channel must be locked during this function all.
  *
- * \param the framehook list
+ * \param framehooks the framehook list
  * \retval 0, not empty
  * \retval 1, is empty
  */

include/asterisk/heap.h

@@ -213,6 +213,7 @@ size_t ast_heap_size(struct ast_heap *h);
  * \brief Write-Lock a heap
  *
  * \param h the heap
+ * \param file, func, line
  *
  * A lock is provided for convenience.  It can be assumed that none of the
  * ast_heap API calls are thread safe.  This lock does not have to be used
@@ -227,6 +228,7 @@ int __ast_heap_wrlock(struct ast_heap *h, const char *file, const char *func, in
  * \brief Read-Lock a heap
  *
  * \param h the heap
+ * \param file, func, line
  *
  * A lock is provided for convenience.  It can be assumed that none of the
  * ast_heap API calls are thread safe.  This lock does not have to be used
@@ -241,6 +243,7 @@ int __ast_heap_rdlock(struct ast_heap *h, const char *file, const char *func, in
  * \brief Unlock a heap
  *
  * \param h the heap
+ * \param file, func, line
  *
  * \return see the documentation for pthread_rwlock_unlock()
  * \since 1.6.1

include/asterisk/manager.h

@@ -247,7 +247,9 @@ int astman_verify_session_writepermissions(uint32_t ident, int perm);
  * \param event Event name
  * \param chancount Number of channels in chans parameter
  * \param chans A pointer to an array of channels involved in the event
+ * \param file, line, func
  * \param contents Format string describing event
+ * \param ...
  * \since 1.8
 */
 int __ast_manager_event_multichan(int category, const char *event, int chancount,

include/asterisk/message.h

@@ -167,6 +167,7 @@ int __attribute__((format(printf, 2, 3)))
  * \brief Set a variable on the message going to the dialplan.
  * \note Setting a variable that already exists overwrites the existing variable value
  *
+ * \param msg
  * \param name Name of variable to set
  * \param value Value of variable to set
  *
@@ -179,6 +180,7 @@ int ast_msg_set_var(struct ast_msg *msg, const char *name, const char *value);
  * \brief Set a variable on the message being sent to a message tech directly.
  * \note Setting a variable that already exists overwrites the existing variable value
  *
+ * \param msg
  * \param name Name of variable to set
  * \param value Value of variable to set
  *

include/asterisk/netsock2.h

@@ -73,7 +73,7 @@ struct ast_sockaddr {
  * if you know what you're doing.
  *
  * \param addr The IPv4-mapped address to convert
- * \param mapped_addr The resulting IPv4 address
+ * \param ast_mapped The resulting IPv4 address
  * \retval 0 Unable to make the conversion
  * \retval 1 Successful conversion
  */
@@ -310,10 +310,10 @@ static inline char *ast_sockaddr_stringify_port(const struct ast_sockaddr *addr)
  * \brief
  * Splits a string into its host and port components
  *
- * \param str[in]   The string to parse. May be modified by writing a NUL at the end of
+ * \param[in] str The string to parse. May be modified by writing a NUL at the end of
  *                  the host part.
- * \param host[out] Pointer to the host component within \a str.
- * \param port[out] Pointer to the port component within \a str.
+ * \param[out] host Pointer to the host component within \a str.
+ * \param[out] port Pointer to the port component within \a str.
  * \param flags     If set to zero, a port MAY be present. If set to PARSE_PORT_IGNORE, a
  *                  port MAY be present but will be ignored. If set to PARSE_PORT_REQUIRE,
  *                  a port MUST be present. If set to PARSE_PORT_FORBID, a port MUST NOT
@@ -467,7 +467,7 @@ int ast_sockaddr_is_ipv4_mapped(const struct ast_sockaddr *addr);
  * \brief
  * Determine if an IPv4 address is a multicast address
  *
- * \parm addr the address to check
+ * \param addr the address to check
  *
  * This function checks if an address is in the 224.0.0.0/4 network block.
  *
@@ -647,9 +647,9 @@ int _ast_sockaddr_to_sin(const struct ast_sockaddr *addr,
 /*!
  * \since 1.8
  *
- * \brief
- * Converts a struct sockaddr_in to a struct ast_sockaddr.
+ * \brief Converts a struct sockaddr_in to a struct ast_sockaddr.
  *
+ * \param addr
  * \param sin The sockaddr_in to convert
  * \return an ast_sockaddr structure
  */

include/asterisk/pbx.h

@@ -821,7 +821,7 @@ int ast_context_add_include(const char *context, const char *include,
  * \brief Add a context include
  *
  * \param con context to add the include to
- * \param include include to add
+ * \param value include include to add
  * \param registrar who registered the context
  *
  * Adds an include taking a struct ast_context as the first parameter

include/asterisk/presencestate.h

@@ -62,9 +62,9 @@ enum ast_presence_state ast_presence_state_val(const char *val);
 /*!
  * \brief Asks a presence state provider for the current presence state.
  *
- * \param presence_provider, The presence provider to retrieve the state from.
- * \param subtype, The output paramenter to store the subtype string in. Must be freed if returned
- * \param message, The output paramenter to store the message string in. Must be freed if returned
+ * \param presence_provider The presence provider to retrieve the state from.
+ * \param subtype The output paramenter to store the subtype string in. Must be freed if returned
+ * \param message The output paramenter to store the message string in. Must be freed if returned
  *
  * \retval presence state value on success,
  * \retval -1 on failure.
@@ -78,9 +78,9 @@ enum ast_presence_state ast_presence_state(const char *presence_provider, char *
  * requested (such as a base64 decode). In such instances, use of the event cache is not suitable
  * and should be bypassed.
  *
- * \param presence_provider, The presence provider to retrieve the state from.
- * \param subtype, The output paramenter to store the subtype string in. Must be freed if returned
- * \param message, The output paramenter to store the message string in. Must be freed if returned
+ * \param presence_provider The presence provider to retrieve the state from.
+ * \param subtype The output paramenter to store the subtype string in. Must be freed if returned
+ * \param message The output paramenter to store the message string in. Must be freed if returned
  *
  * \retval presence state value on success,
  * \retval -1 on failure.

include/asterisk/rtp_engine.h

@@ -1164,7 +1164,7 @@ struct ast_format *ast_rtp_codecs_get_payload_format(struct ast_rtp_codecs *code
  * \brief Get the sample rate associated with known RTP payload types
  *
  * \param asterisk_format True if the value in format is to be used.
- * \param An asterisk format
+ * \param format An asterisk format
  * \param code from AST_RTP list
  *
  * \return the sample rate if the format was found, zero if it was not found
@@ -1815,7 +1815,7 @@ void ast_rtp_instance_set_hold_timeout(struct ast_rtp_instance *instance, int ti
  * \brief Set the RTP keepalive interval
  *
  * \param instance The RTP instance
- * \param period Value to set the keepalive interval to
+ * \param timeout Value to set the keepalive interval to
  *
  * Example usage:
  *

include/asterisk/strings.h

@@ -804,6 +804,8 @@ AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_set_va(struct a
  * \brief Append to a dynamic string using a va_list
  *
  * Same as ast_str_set_va(), but append to the current content.
+ *
+ * \param buf, max_len, fmt, ap
  */
 AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_append_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap),
 {

include/asterisk/translate.h

@@ -236,7 +236,7 @@ struct ast_trans_pvt;
  * \brief Register a translator
  * This registers a codec translator with asterisk
  * \param t populated ast_translator structure
- * \param module handle to the module that owns this translator
+ * \param mod module handle to the module that owns this translator
  * \return 0 on success, -1 on failure
  */
 int __ast_register_translator(struct ast_translator *t, struct ast_module *module);
@@ -276,10 +276,10 @@ void ast_translator_deactivate(struct ast_translator *t);
  * Given a list of sources, and a designed destination format, which should
  * I choose?
  *
- * \param destination capabilities
- * \param source capabilities
- * \param destination format chosen out of destination capabilities
- * \param source format chosen out of source capabilities
+ * \param dst_cap destination capabilities
+ * \param src_cap source capabilities
+ * \param dst_fmt_out destination format chosen out of destination capabilities
+ * \param src_fmt_out source format chosen out of source capabilities
  * \return Returns 0 on success, -1 if no path could be found.
  *
  * \note dst_cap and src_cap are not mondified.
@@ -292,8 +292,8 @@ int ast_translator_best_choice(struct ast_format_cap *dst_cap,
 /*! 
  * \brief Builds a translator path
  * Build a path (possibly NULL) from source to dest 
- * \param dest destination format
- * \param source source format
+ * \param dst dest destination format
+ * \param src source source format
  * \return ast_trans_pvt on success, NULL on failure
  * */
 struct ast_trans_pvt *ast_translator_build_path(struct ast_format *dest, struct ast_format *source);
@@ -309,7 +309,7 @@ void ast_translator_free_path(struct ast_trans_pvt *tr);
  * \brief translates one or more frames
  * Apply an input frame into the translator and receive zero or one output frames.  Consume
  * determines whether the original frame should be freed
- * \param tr translator structure to use for translation
+ * \param path tr translator structure to use for translation
  * \param f frame to translate
  * \param consume Whether or not to free the original frame
  * \return an ast_frame of the new translation format on success, NULL on failure
@@ -342,8 +342,8 @@ void ast_translate_available_formats(struct ast_format_cap *dest, struct ast_for
 
 /*!
  * \brief Puts a string representation of the translation path into outbuf
- * \param translator structure containing the translation path
- * \param ast_str output buffer
+ * \param t translator structure containing the translation path
+ * \param str ast_str output buffer
  * \retval on success pointer to beginning of outbuf. on failure "".
  */
 const char *ast_translate_path_to_str(struct ast_trans_pvt *t, struct ast_str **str);

include/asterisk/utils.h

@@ -858,7 +858,6 @@ int ast_eid_cmp(const struct ast_eid *eid1, const struct ast_eid *eid2);
 
 /*!
  * \brief Get current thread ID
- * \param None
  * \return the ID if platform is supported, else -1
  */
 int ast_get_tid(void);
@@ -897,12 +896,14 @@ char *ast_utils_which(const char *binary, char *fullpath, size_t fullpath_size);
  *     RAII_VAR(struct mything *, thing, mything_alloc(name), mything_cleanup);
  *     ...
  * }
+ * \endcode
  *
  * \note This macro is especially useful for working with ao2 objects. A common idiom
  * would be a function that needed to look up an ao2 object and might have several error
  * conditions after the allocation that would normally need to unref the ao2 object.
  * With RAII_VAR, it is possible to just return and leave the cleanup to the destructor
  * function. For example:
+ *
  * \code
  * void do_stuff(const char *name)
  * {
@@ -915,7 +916,7 @@ char *ast_utils_which(const char *binary, char *fullpath, size_t fullpath_size);
  *     }
  *     do_stuff_with_thing(thing);
  * }
- * \encode
+ * \endcode
  */
 #define RAII_VAR(vartype, varname, initval, dtor) \
     auto void _dtor_ ## varname (vartype * v); \

main/audiohook.c

@@ -99,7 +99,7 @@ static int audiohook_set_internal_rate(struct ast_audiohook *audiohook, int rate
 /*! \brief Initialize an audiohook structure
  * \param audiohook Audiohook structure
  * \param type
- * \param source
+ * \param init, source, init_flags
  * \return Returns 0 on success, -1 on failure
  */
 int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source, enum ast_audiohook_init_flags init_flags)

main/cdr.c

@@ -1013,7 +1013,10 @@ char *ast_cdr_disp2str(int disposition)
 	return "UNKNOWN";
 }
 
-/*! Converts AMA flag to printable string */
+/*! Converts AMA flag to printable string 
+ *
+ * \param flag, flags
+ */
 char *ast_cdr_flags2str(int flag)
 {
 	switch (flag) {

main/channel.c

@@ -811,7 +811,10 @@ int ast_str2cause(const char *name)
 }
 
 /*! \brief Gives the string form of a given channel state.
-	\note This function is not reentrant.
+ *
+ * \note This function is not reentrant.
+ *
+ * \param state
  */
 const char *ast_state2str(enum ast_channel_state state)
 {

main/file.c

@@ -601,12 +601,12 @@ static int fileexists_test(const char *filename, const char *fmt, const char *la
  * \note The last parameter(s) point to a buffer of sufficient size,
  * which on success is filled with the matching filename.
  *
- * \param filename, name of the file.
- * \param fmt, format to look for the file in. OPTIONAL
- * \param preflang, the perfered language
- * \param buf, returns the matching filename
- * \param buflen, size of the buf
- * \param result_cap, OPTIONAL format capabilities result structure
+ * \param filename Name of the file.
+ * \param fmt Format to look for the file in. OPTIONAL
+ * \param preflang The perfered language
+ * \param buf Returns the matching filename
+ * \param buflen Size of the buf
+ * \param result_cap OPTIONAL format capabilities result structure
  *        returns what formats the file was found in.
  *
  * \retval 1, true. file exists and result format is set

main/named_acl.c

@@ -195,7 +195,7 @@ void *named_acl_alloc(const char *cat)
  * \brief Find a named ACL in a container by its name
  *
  * \param container ao2container holding the named ACLs
- * \param name of the ACL wanted to be found
+ * \param cat name of the ACL wanted to be found
  * \retval pointer to the named ACL if available. Null if not found.
  */
 void *named_acl_find(struct ao2_container *container, const char *cat)

main/pbx.c

@@ -6794,6 +6794,7 @@ int ast_context_remove_extension_callerid2(struct ast_context *con, const char *
  * \note This function locks contexts list by &conlist, searches for the right context
  * structure, and locks the macrolock mutex in that context.
  * macrolock is used to limit a macro to be executed by one call at a time.
+ * \param context The context
  */
 int ast_context_lockmacro(const char *context)
 {
@@ -6815,6 +6816,7 @@ int ast_context_lockmacro(const char *context)
  * \note This function locks contexts list by &conlist, searches for the right context
  * structure, and unlocks the macrolock mutex in that context.
  * macrolock is used to limit a macro to be executed by one call at a time.
+ * \param context The context
  */
 int ast_context_unlockmacro(const char *context)
 {
@@ -8796,7 +8798,12 @@ static const char * const months[] =
 	"dec",
 	NULL,
 };
-
+/*! /brief Build timing
+ *
+ * /param i, info
+ * /param info_in
+ *
+ */
 int ast_build_timing(struct ast_timing *i, const char *info_in)
 {
 	char *info;

pbx/pbx_lua.c

@@ -422,7 +422,6 @@ static void lua_update_registry(lua_State *L, const char *context, const char *e
  * The value on the top of the stack is popped and used as the name.
  *
  * \param L the lua_State to use
- * \param name the name of the variable
  */
 static void lua_push_variable_table(lua_State *L)
 {