Fix some doxygen warnings.

(closes issue #17336)
Reported by: snuffy
Patches:
      doxygen-fixes1.diff uploaded by snuffy (license 35)
Tested by: russell

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

include/asterisk/app.h

@@ -136,6 +136,7 @@ int ast_app_run_macro(struct ast_channel *autoservice_chan, struct ast_channel
 
 /*!
  * \brief Set voicemail function callbacks
+ * \param[in] has_voicemail_func set function pointer
  * \param[in] inboxcount2_func set function pointer
  * \param[in] sayname_func set function pointer
  * \param[in] inboxcount_func set function pointer

include/asterisk/astmm.h

@@ -19,7 +19,7 @@
 /*! \file
  * \brief Asterisk memory usage debugging
  * This file provides headers for MALLOC_DEBUG, a define used for tracking down
- * memory leaks.  It should never be #included directly; always use the
+ * memory leaks.  It should never be \#included directly; always use the
  * MALLOC_DEBUG definition in menuselect to activate those functions.
  */
 

include/asterisk/astobj2.h

@@ -431,6 +431,7 @@ void *__ao2_alloc(const size_t data_size, ao2_destructor_fn destructor_fn);
  *
  * \param o A pointer to the object
  * \param delta Value to add to the reference counter.
+ * \param tag used for debugging
  * \return The value of the reference counter before the operation.
  *
  * Increase/decrease the reference counter according
@@ -695,13 +696,15 @@ struct ao2_container;
  * We allocate space for a struct astobj_container, struct container
  * and the buckets[] array.
  *
- * \param n_buckets Number of buckets for hash
- * \param hash_fn Pointer to a function computing a hash value.
- * \param cmp_fn Pointer to a function comparating key-value
+ * \param arg1 Number of buckets for hash
+ * \param arg2 Pointer to a function computing a hash value.
+ * \param arg3 Pointer to a function comparating key-value
  * 			with a string. (can be NULL)
+ * \param arg4
+ *
  * \return A pointer to a struct container.
  *
- * destructor is set implicitly.
+ * \note Destructor is set implicitly.
  */
 
 #if defined(REF_DEBUG)
@@ -746,10 +749,11 @@ int ao2_container_count(struct ao2_container *c);
 /*!
  * \brief Add an object to a container.
  *
- * \param c the container to operate on.
- * \param newobj the object to be added.
+ * \param arg1 the container to operate on.
+ * \param arg2 the object to be added.
+ * \param arg3 used for debuging.
  *
- * \retval NULL on errors
+ * \retval NULL on errors.
  * \retval newobj on success.
  *
  * This function inserts an object in a container according its key.
@@ -777,8 +781,9 @@ void *__ao2_link(struct ao2_container *c, void *newobj);
 /*!
  * \brief Remove an object from a container
  *
- * \param c the container
- * \param obj the object to unlink
+ * \param arg1 the container
+ * \param arg2 the object to unlink
+ * \param arg3 tag for debugging
  *
  * \retval NULL, always
  *
@@ -837,6 +842,7 @@ void *__ao2_unlink(struct ao2_container *c, void *obj);
           flags is the same as flags passed into ao2_callback (flags are
            also used by ao2_callback).
  * \param arg passed to the callback.
+ * \param tag used for debuging.
  * \return when OBJ_MULTIPLE is not included in the flags parameter,
  *         the return value will be either the object found or NULL if no
  *         no matching object was found. if OBJ_MULTIPLE is included,

include/asterisk/bridging_technology.h

@@ -83,7 +83,7 @@ struct ast_bridge_technology {
 /*! \brief Register a bridge technology for use
  *
  * \param technology The bridge technology to register
- * \param module The module that is registering the bridge technology
+ * \param mod The module that is registering the bridge technology
  *
  * \retval 0 on success
  * \retval -1 on failure

include/asterisk/calendar.h

@@ -146,7 +146,7 @@ int ast_calendar_register(struct ast_calendar_tech *tech);
  * \param tech calendar technology to unregister
  *
  * \retval 0 success
- * \retva -1 failure
+ * \retval -1 failure
  */
 void ast_calendar_unregister(struct ast_calendar_tech *tech);
 

include/asterisk/callerid.h

@@ -181,9 +181,14 @@ int ast_callerid_generate(unsigned char *buf, const char *name, const char *numb
 
 /*!
  * \brief Generate message waiting indicator
+ * \param buf
  * \param active The message indicator state
  *  -- either 0 no messages in mailbox or 1 messages in mailbox
  * \param type Format of message (any of CID_MWI_TYPE_*)
+ * \param codec
+ * \param name
+ * \param number
+ * \param flags
  * \see callerid_generate() for more info as it uses the same encoding
  * \version 1.6.1 changed mdmf parameter to type, added name, number and flags for caller id message generation
  */

include/asterisk/ccss.h

@@ -1321,6 +1321,7 @@ int ast_cc_monitor_count(const char * const name, const char * const type);
  * up the ladder correctly.
  *
  * \param core_id The core ID of the corresponding CC transaction
+ * \param debug
  * \retval 0 Request successfully queued
  * \retval -1 Request could not be queued
  */
@@ -1377,7 +1378,7 @@ int ast_setup_cc_recall_datastore(struct ast_channel *chan, const int core_id);
  * sure that you have no potential lock order issues here.
  *
  * \param chan The channel to check
- * \param core_id[out] If this is a valid CC recall, the core_id of the failed call
+ * \param[out] core_id If this is a valid CC recall, the core_id of the failed call
  * will be placed in this output parameter
  * \param monitor_type Clarify which type of monitor type we are looking for if this
  * is happening on a called channel. For incoming channels, this parameter is not used.
@@ -1508,7 +1509,8 @@ void ast_cc_busy_interface(struct ast_channel *inbound, struct ast_cc_config_par
  * ready, and then based on set flags, creates the proper frame type. For chan_dahdi, we
  * provide this function. It provides us the data we need, and we'll make its frame for it.
  *
- * \param chan A channel involved in the call. What we want is on a datastore on both incoming and outgoing so either may be provided
+ * \param chan A channel involved in the call. What we want is on a datastore on both incoming 
+ * and outgoing so either may be provided
  * \param cc_params The CC configuration parameters for the outbound target
  * \param monitor_type The type of monitor to use when CC is requested
  * \param device_name The name of the outbound target device.
@@ -1518,8 +1520,8 @@ void ast_cc_busy_interface(struct ast_channel *inbound, struct ast_cc_config_par
  * data has been allocated, then this parameter should contain a pointer to that data. If using a generic
  * monitor, this parameter should remain NULL. Note that if this function should fail at some point,
  * it is the responsibility of the caller to free the private data upon return.
- * \param[out] frame. The frame we will be returning to the caller. It is vital that ast_frame_free be called on this frame since the
- * payload will be allocated on the heap.
+ * \param[out] frame The frame we will be returning to the caller. It is vital that ast_frame_free be 
+ * called on this frame since the payload will be allocated on the heap.
  * \retval -1 Failure. At some point there was a failure. Do not attempt to use the frame in this case.
  * \retval 0 Success
  */
@@ -1561,6 +1563,7 @@ typedef void (*ast_cc_callback_fn)(struct ast_channel *chan, struct ast_cc_confi
  * See the explanation in ast_channel_tech::cc_callback for more
  * details.
  *
+ * \param inbound
  * \param tech Channel technology to use
  * \param dest Channel/group/peer or whatever the specific technology uses
  * \param callback Function to call when a target is reached

include/asterisk/channel.h

@@ -1129,6 +1129,7 @@ struct ast_channel *ast_channel_release(struct ast_channel *chan);
  *
  * \param type type of channel to request
  * \param format requested channel format (codec)
+ * \param requestor channel asking for data
  * \param data data to pass to the channel requester
  * \param status status
  *
@@ -1147,6 +1148,7 @@ struct ast_channel *ast_request(const char *type, format_t format, const struct
  *
  * \param type type of channel to request
  * \param format requested channel format
+ * \param requestor channel asking for data
  * \param data data to pass to the channel requester
  * \param timeout maximum amount of time to wait for an answer
  * \param reason why unsuccessful (if unsuccessful)
@@ -1164,6 +1166,7 @@ struct ast_channel *ast_request_and_dial(const char *type, format_t format, cons
  * by the low level module and attempt to place a call on it
  * \param type type of channel to request
  * \param format requested channel format
+ * \param requestor channel requesting data
  * \param data data to pass to the channel requester
  * \param timeout maximum amount of time to wait for an answer
  * \param reason why unsuccessful (if unsuccessful)
@@ -1282,6 +1285,7 @@ int ast_softhangup_nolock(struct ast_channel *chan, int reason);
  *
  * \param chan channel to set the field on
  * \param source a string describing the source of the hangup for this channel
+ * \param force
  *
  * \since 1.8
  *
@@ -1937,6 +1941,7 @@ int ast_autoservice_start(struct ast_channel *chan);
  * ast_autoservice_stop and the autoservice thread. It is important
  * that chan is not locked prior to this call
  *
+ * \param chan
  * \retval 0 success
  * \retval -1 error, or the channel has been hungup
  */
@@ -1945,7 +1950,10 @@ int ast_autoservice_stop(struct ast_channel *chan);
 /*!
  * \brief Enable or disable timer ticks for a channel
  *
+ * \param c channel
  * \param rate number of timer ticks per second
+ * \param func callback function
+ * \param data
  *
  * \details
  * If timers are supported, force a scheduled expiration on the
@@ -2912,7 +2920,7 @@ struct ast_cc_config_params *ast_channel_get_cc_config_params(struct ast_channel
  * name is used instead.
  *
  * \param chan The channel to retrieve the information from
- * \param device_name[out] The buffer to place the device's name into
+ * \param[out] device_name The buffer to place the device's name into
  * \param name_buffer_length The allocated space for the device_name
  * \return 0 always
  */

include/asterisk/data.h

@@ -601,7 +601,7 @@ struct ast_data *ast_data_add_ptr(struct ast_data *root, const char *childname,
  * \brief Add a string node type.
  * \param[in] root The root of the ast_data to insert into.
  * \param[in] childname The name of the child element to be added.
- * \param[in] value The value for the new node.
+ * \param[in] string The value for the new node.
  * \retval NULL on error (memory exhaustion only).
  * \retval non-NULL a newly allocated node.
  */
@@ -612,7 +612,7 @@ struct ast_data *ast_data_add_str(struct ast_data *root, const char *childname,
  * \brief Add a boolean node type.
  * \param[in] root The root of the ast_data to insert into.
  * \param[in] childname The name of the child element to be added.
- * \param[in] value The value for the new node.
+ * \param[in] boolean The value for the new node.
  * \retval NULL on error (memory exhaustion only).
  * \retval non-NULL a newly allocated node.
  */

include/asterisk/dnsmgr.h

@@ -42,7 +42,7 @@ struct ast_dnsmgr_entry;
  *
  * \param name the hostname
  * \param result where the DNS manager should store the IP address as it refreshes it.
- *      it.
+ * \param service
  *
  * This function allocates a new DNS manager entry object, and fills it with the
  * provided hostname and IP address.  This function does not force an initial lookup
@@ -69,6 +69,7 @@ void ast_dnsmgr_release(struct ast_dnsmgr_entry *entry);
  * \param name the hostname
  * \param result where to store the IP address as the DNS manager refreshes it
  * \param dnsmgr Where to store the allocate DNS manager entry
+ * \param service
  *
  * This function allocates a new DNS manager entry object, and fills it with
  * the provided hostname and IP address.  This function _does_ force an initial

include/asterisk/doxyref.h

@@ -345,7 +345,7 @@
 /*! 
  * \page Config_fea Call features configuration
  * \par See also
- * \arg \ref res_features.c : Call feature implementation
+ * \arg \ref features.c : Call feature implementation
  * \section featconf features.conf
  * \verbinclude features.conf.sample
  */

include/asterisk/event.h

@@ -192,7 +192,8 @@ int ast_event_sub_append_ie_str(struct ast_event_sub *sub,
  *
  * \param sub the dynamic subscription allocated with ast_event_subscribe_new()
  * \param ie_type the information element type for the parameter
- * \param raw the data that must be present in the event to match this subscription
+ * \param data the data that must be present in the event to match this subscription
+ * \param raw_datalen length of data
  *
  * \retval 0 success
  * \retval non-zero failure
@@ -480,7 +481,7 @@ int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie
  *
  * \param event the event that the IE will be appended to
  * \param ie_type the type of IE to append
- * \param flags the flags that are the payload of the IE
+ * \param bitflags the flags that are the payload of the IE
  *
  * \retval 0 success
  * \retval -1 failure

include/asterisk/features.h

@@ -120,26 +120,34 @@ int ast_bridge_call(struct ast_channel *chan, struct ast_channel *peer,struct as
 /*! \brief Pickup a call */
 int ast_pickup_call(struct ast_channel *chan);
 
-/*! \brief register new feature into feature_set 
-   \param feature an ast_call_feature object which contains a keysequence
-   and a callback function which is called when this keysequence is pressed
-   during a call. */
+/*! 
+ * \brief register new feature into feature_set 
+ * \param feature an ast_call_feature object which contains a keysequence
+ * and a callback function which is called when this keysequence is pressed
+ * during a call. 
+*/
 void ast_register_feature(struct ast_call_feature *feature);
 
-/*! \brief unregister feature from feature_set
-    \param feature the ast_call_feature object which was registered before*/
+/*! 
+ * \brief unregister feature from feature_set
+ * \param feature the ast_call_feature object which was registered before
+*/
 void ast_unregister_feature(struct ast_call_feature *feature);
 
-/*! \brief detect a feature before bridging 
-    \param chan
-    \param ast_flags ptr
-    \param char ptr of input code
-    \retval ast_call_feature ptr to be set if found 
-    \return result, was feature found or not */
+/*! 
+ * \brief detect a feature before bridging 
+ * \param chan
+ * \param features an ast_flags ptr
+ * \param code ptr of input code
+ * \param feature
+ * \retval ast_call_feature ptr to be set if found 
+*/
 int ast_feature_detect(struct ast_channel *chan, struct ast_flags *features, const char *code, struct ast_call_feature *feature);
 
-/*! \brief look for a call feature entry by its sname
-	\param name a string ptr, should match "automon", "blindxfer", "atxfer", etc. */
+/*! 
+ * \brief look for a call feature entry by its sname
+ * \param name a string ptr, should match "automon", "blindxfer", "atxfer", etc. 
+*/
 struct ast_call_feature *ast_find_call_feature(const char *name);
 
 void ast_rdlock_call_features(void);
@@ -148,8 +156,9 @@ void ast_unlock_call_features(void);
 /*! \brief Reload call features from features.conf */
 int ast_features_reload(void);
 
-/* !\brief parse L option and read associated channel variables to set warning, warning frequency, and timelimit
-	\note caller must be aware of freeing memory for warning_sound, end_sound, and start_sound
+/*!
+ * \brief parse L option and read associated channel variables to set warning, warning frequency, and timelimit
+ * \note caller must be aware of freeing memory for warning_sound, end_sound, and start_sound
 */
 int ast_bridge_timelimit(struct ast_channel *chan, struct ast_bridge_config *config, char *parse, struct timeval *calldurationlimit);
 

include/asterisk/http.h

@@ -171,8 +171,8 @@ void ast_http_error(struct ast_tcptls_session_instance *ser, int status, const c
 
 /*!
  * \brief Return the current prefix
- * \param buf[out] destination buffer for previous
- * \param len[in] length of prefix to copy
+ * \param[out] buf destination buffer for previous
+ * \param[in] len length of prefix to copy
  * \since 1.6.1
  */
 void ast_http_prefix(char *buf, int len);

include/asterisk/logger.h

@@ -182,14 +182,14 @@ void ast_console_toggle_loglevel(int fd, int level, int state);
 
 /*!
  * \brief Get the debug level for a module
- * \param file the filename
+ * \param module the name of module
  * \return the debug level
  */
 unsigned int ast_debug_get_by_module(const char *module);
 
 /*!
  * \brief Get the verbose level for a module
- * \param file the filename
+ * \param module the name of module
  * \return the verbose level
  */
 unsigned int ast_verbose_get_by_module(const char *module);

include/asterisk/manager.h

@@ -118,7 +118,7 @@ void ast_manager_register_hook(struct manager_custom_hook *hook);
 void ast_manager_unregister_hook(struct manager_custom_hook *hook);
 
 /*! \brief Registered hooks can call this function to invoke actions and they will receive responses through registered callback
- * \param hookid the file identifier specified in manager_custom_hook struct when registering a hook
+ * \param hook the file identifier specified in manager_custom_hook struct when registering a hook
  * \param msg ami action mesage string e.g. "Action: SipPeers\r\n"
 
  * \retval 0 on Success

include/asterisk/pbx.h

@@ -380,7 +380,7 @@ int ast_add_extension2(struct ast_context *con, int replace, const char *extensi
 /*!
  * \brief Map devstate to an extension state.
  *
- * \param[in] device state
+ * \param[in] devstate device state
  *
  * \return the extension state mapping.
  */
@@ -725,8 +725,6 @@ int ast_context_remove_switch2(struct ast_context *con, const char *sw,
  * \param context context to remove extension from
  * \param extension which extension to remove
  * \param priority priority of extension to remove (0 to remove all)
- * \param callerid NULL to remove all; non-NULL to match a single record per priority
- * \param matchcid non-zero to match callerid element (if non-NULL); 0 to match default case
  * \param registrar registrar of the extension
  *
  * This function removes an extension from a given context.

include/asterisk/rtp_engine.h

@@ -603,6 +603,7 @@ void *ast_rtp_instance_get_data(struct ast_rtp_instance *instance);
  * \brief Send a frame out over RTP
  *
  * \param instance The RTP instance to send frame out on
+ * \param frame the frame to send out
  *
  * \retval 0 success
  * \retval -1 failure
@@ -872,7 +873,7 @@ void ast_rtp_codecs_payloads_default(struct ast_rtp_codecs *codecs, struct ast_r
  * \brief Copy payload information from one RTP instance to another
  *
  * \param src The source codecs structure
- * \param dst The destination codecs structure that the values from src will be copied to
+ * \param dest The destination codecs structure that the values from src will be copied to
  * \param instance Optionally the instance that the dst codecs structure belongs to
  *
  * Example usage:
@@ -934,7 +935,7 @@ int ast_rtp_codecs_payloads_set_rtpmap_type(struct ast_rtp_codecs *codecs, struc
 /*!
  * \brief Set payload type to a known MIME media type for a codec with a specific sample rate
  *
- * \param rtp RTP structure to modify
+ * \param codecs RTP structure to modify
  * \param instance Optionally the instance that the codecs structure belongs to
  * \param pt Payload type entry to modify
  * \param mimetype top-level MIME type of media stream (typically "audio", "video", "text", etc.)
@@ -1012,7 +1013,7 @@ unsigned int ast_rtp_lookup_sample_rate2(int asterisk_format, format_t code);
  * \brief Retrieve all formats that were found
  *
  * \param codecs Codecs structure to look in
- * \param astFormats An integer to put the Asterisk formats in
+ * \param astformats An integer to put the Asterisk formats in
  * \param nonastformats An integer to put the non-Asterisk formats in
  *
  * Example usage:

include/asterisk/smdi.h

@@ -122,7 +122,7 @@ AST_OPTIONAL_API(struct ast_smdi_md_message *, ast_smdi_md_message_wait,
 /*!
  * \brief Put an SMDI message back in the front of the queue.
  * \param iface a pointer to the interface to use.
- * \param md_msg a pointer to the message to use.
+ * \param msg a pointer to the message to use.
  *
  * This function puts a message back in the front of the specified queue.  It
  * should be used if a message was popped but is not going to be processed for
@@ -169,7 +169,7 @@ AST_OPTIONAL_API(struct ast_smdi_mwi_message *, ast_smdi_mwi_message_wait_statio
 /*!
  * \brief Put an SMDI message back in the front of the queue.
  * \param iface a pointer to the interface to use.
- * \param mwi_msg a pointer to the message to use.
+ * \param msg a pointer to the message to use.
  *
  * This function puts a message back in the front of the specified queue.  It
  * should be used if a message was popped but is not going to be processed for

include/asterisk/threadstorage.h

@@ -88,11 +88,11 @@ void __ast_threadstorage_object_replace(void *key_old, void *key_new, size_t len
 /*!
  * \brief Define a thread storage variable, with custom initialization and cleanup
  *
- * \param name The name of the thread storage object
- * \param init This is a custom function that will be called after each thread specific
+ * \param a The name of the thread storage object
+ * \param b This is a custom function that will be called after each thread specific
  *           object is allocated, with the allocated block of memory passed
  *           as the argument.
- * \param cleanup This is a custom function that will be called instead of ast_free
+ * \param c This is a custom function that will be called instead of ast_free
  *              when the thread goes away.  Note that if this is used, it *MUST*
  *              call free on the allocated memory.
  *

include/asterisk/timing.h

@@ -84,7 +84,7 @@ struct ast_timing_interface {
 /*!
  * \brief Register a set of timing functions.
  *
- * \param funcs An instance of the \c ast_timing_interfaces structure with pointers
+ * \param i An instance of the \c ast_timing_interfaces structure with pointers
  *        to the functions provided by the timing implementation.
  *
  * \retval NULL failure 

include/asterisk/xml.h

@@ -90,7 +90,7 @@ void ast_xml_close(struct ast_xml_doc *doc);
 
 /*! \brief Open an XML document that resides in memory.
  * \param buffer The address where the document is stored
- * \size The number of bytes in the document
+ * \param size The number of bytes in the document
  * \retval NULL on error.
  * \retval The ast_xml_doc reference to the open document.
  */
@@ -119,7 +119,7 @@ void ast_xml_free_node(struct ast_xml_node *node);
 
 /*!
  * \brief Free an attribute returned by ast_xml_get_attribute()
- * \param data pointer to be freed.
+ * \param attribute pointer to be freed.
  */
 void ast_xml_free_attr(const char *attribute);
 
@@ -157,11 +157,11 @@ int ast_xml_set_attribute(struct ast_xml_node *node, const char *name, const cha
 
 /*!
  * \brief Find a node element by name.
- * \param node This is the node starting point.
+ * \param root_node This is the node starting point.
  * \param name Node name to find.
  * \param attrname attribute name to match (if NULL it won't be matched).
  * \param attrvalue attribute value to match (if NULL it won't be matched).
- * \retval NULL if not found
+ * \retval NULL if not found.
  * \retval The node on success.
  */
 struct ast_xml_node *ast_xml_find_element(struct ast_xml_node *root_node, const char *name, const char *attrname, const char *attrvalue);