doxygen: Fix doxygen errors.

Change-Id: Ic50e95b4fc10f74ab15416d908e8a87ee8ec2f85

apps/app_mf.c

@@ -235,6 +235,7 @@ static const char sendmf_name[] = "SendMF";
  * \param buflen Size of buffer
  * \param timeout ms to wait for all digits before giving up
  * \param features Any additional DSP features to use
+ * \param laxkp Receive digits even if KP not received
  * \param override Start over if we receive additional KPs
  * \param no_kp Don't include KP in the output
  * \param no_st Don't include start digits in the output

include/asterisk/channel.h

@@ -2255,8 +2255,8 @@ int ast_senddigit_mf_end(struct ast_channel *chan);
  * \param chan channel to act upon
  * \param digit the MF digit to send, encoded in ASCII
  * \param duration the duration of a numeric digit ending in ms
- * \param duration the duration of a KP digit ending in ms
+ * \param durationkp the duration of a KP digit ending in ms
- * \param duration the duration of a ST, STP, ST2P, or ST3P digit ending in ms
+ * \param durationst the duration of a ST, STP, ST2P, or ST3P digit ending in ms
  * \param is_external 1 if called by a thread that is not the channel's media
  *                handler thread, 0 if called by the channel's media handler
  *                thread.

include/asterisk/crypto.h

@@ -110,10 +110,10 @@ AST_OPTIONAL_API(int, ast_sign_bin, (struct ast_key *key, const char *msg, int m
 
 /*!
  * \brief Encrypt a message using a given private key
- * \param key a private key to use to encrypt
+ * \param dst a pointer to a buffer of at least srclen * 1.5 bytes in which the encrypted
  * \param src the message to encrypt
  * \param srclen the length of the message to encrypt
- * \param dst a pointer to a buffer of at least srclen * 1.5 bytes in which the encrypted
+ * \param key a private key to use to encrypt
  * answer will be stored
  *
  * \retval length of encrypted data on success.
@@ -124,10 +124,10 @@ AST_OPTIONAL_API(int, ast_encrypt_bin, (unsigned char *dst, const unsigned char
 
 /*!
  * \brief Decrypt a message using a given private key
- * \param key a private key to use to decrypt
+ * \param dst a pointer to a buffer of at least srclen bytes in which the decrypted
  * \param src the message to decrypt
  * \param srclen the length of the message to decrypt
- * \param dst a pointer to a buffer of at least srclen bytes in which the decrypted
+ * \param key a private key to use to decrypt
  * answer will be stored
  *
  * \retval length of decrypted data on success.
@@ -164,7 +164,7 @@ AST_OPTIONAL_API(int, ast_aes_set_decrypt_key,
  * \brief AES encrypt data
  * \param in data to be encrypted
  * \param out pointer to a buffer to hold the encrypted output
- * \param ctx address of an aes encryption context filled in with ast_aes_set_encrypt_key
+ * \param key pointer to the ast_aes_encrypt_key to use for encryption
  * \retval <= 0 failure
  * \retval otherwise number of bytes in output buffer
  */
@@ -176,7 +176,7 @@ AST_OPTIONAL_API(int, ast_aes_encrypt,
  * \brief AES decrypt data
  * \param in encrypted data
  * \param out pointer to a buffer to hold the decrypted output
- * \param ctx address of an aes encryption context filled in with ast_aes_set_decrypt_key
+ * \param key pointer to the ast_aes_decrypt_key to use for decryption
  * \retval <= 0 failure
  * \retval otherwise number of bytes in output buffer
  */

include/asterisk/pbx.h

@@ -271,9 +271,9 @@ int pbx_exec(struct ast_channel *c, struct ast_app *app, const char *data);
 /*!
  * \brief Execute an application
  *
- * \param c channel to execute on
+ * \param chan channel to execute on
- * \param app name of app to execute
+ * \param app_name name of app to execute
- * \param data the data passed into the app
+ * \param app_args the data passed into the app
  *
  * This application executes an application by name on a given channel.
  * It is a wrapper around pbx_exec that will perform variable substitution

include/asterisk/res_aeap.h

@@ -55,7 +55,7 @@ struct ao2_container *ast_aeap_client_configs_get(const char *protocol);
 /*!
  * \brief Retrieve codec capabilities from the configuration
  *
- * \param config A configuration object
+ * \param cfg A configuration object
  *
  * \returns The configuration's codec capabilities
  */
@@ -64,7 +64,7 @@ const struct ast_format_cap *ast_aeap_client_config_codecs(const struct ast_aeap
 /*!
  * \brief Check a given protocol against that in an Asterisk external application configuration
  *
- * \param config A configuration object
+ * \param cfg A configuration object
  * \param protocol The protocol to check
  *
  * \returns True if the configuration's protocol matches, false otherwise
@@ -294,7 +294,8 @@ void ast_aeap_user_data_unregister(struct ast_aeap *aeap, const char *id);
  *       handler that [potentially] frees it the caller of this function must ensure
  *       it's done using the returned object before it's unregistered.
  *
- * \param data A user data object
+ * \param aeap An Asterisk external application object
+ * \param id The look up id for the object
  *
  * \returns A user data object
  */
@@ -359,7 +360,6 @@ struct ast_aeap_tsx_params {
  *       is specified in "params".
  *
  * \param aeap An Asterisk external application object
- * \param msg The message to send
  * \param params (optional) Additional parameters to consider when sending. Heap allocation
  *     not required.
  *

include/asterisk/res_aeap_message.h

@@ -241,7 +241,6 @@ struct ast_aeap_message *ast_aeap_message_create_response(const struct ast_aeap_
  * \param name The name of the message
  * \param id Optional id
  * \param error_msg Error message to set
- * \param params Other optional parameter(s) to possibly use
  *
  * \returns An ao2 reference counted AEAP response object, or NULL on error
  */
@@ -315,7 +314,7 @@ const char *ast_aeap_message_name(const struct ast_aeap_message *message);
  * \note Case insensitive
  *
  * \param message A message object
- * \param message name The name to check against
+ * \param name The name to check against
  *
  * \returns True if matched, false otherwise
  */

include/asterisk/res_geolocation.h

@@ -165,7 +165,7 @@ const char *ast_geoloc_validate_result_to_str(enum ast_geoloc_validate_result re
  * \brief Validate that the names of the variables in the list are valid codes or synonyms
  *
  * \param varlist Variable list to check.
- * \param result[OUT] Pointer to char * to receive failing item.
+ * \param[out] result Pointer to char * to receive failing item.
  *
  * \return result code.
  */
@@ -176,7 +176,7 @@ enum ast_geoloc_validate_result ast_geoloc_civicaddr_validate_varlist(
  * \brief Validate that the variables in the list represent a valid GML shape
  *
  * \param varlist Variable list to check.
- * \param result[OUT] Pointer to char * to receive failing item.
+ * \param[out] result Pointer to char * to receive failing item.
  *
  * \return result code.
  */

include/asterisk/res_pjsip.h

@@ -98,8 +98,8 @@
 /*!
  * \brief Fill a buffer with a pjsip transport's remote ip address and port
  *
- * \param transport The pjsip_transport to use
+ * \param _transport The pjsip_transport to use
- * \param dest The destination buffer of at least IP6ADDR_COLON_PORT_BUFLEN bytes
+ * \param _dest The destination buffer of at least IP6ADDR_COLON_PORT_BUFLEN bytes
  */
 #define AST_SIP_MAKE_REMOTE_IPADDR_PORT_STR(_transport, _dest) \
 	snprintf(_dest, IP6ADDR_COLON_PORT_BUFLEN, \
@@ -1094,8 +1094,8 @@ extern pjsip_media_type pjsip_media_type_text_plain;
 /*!
  * \brief Compare pjsip media types
  *
- * \param pjsip_media_type a
+ * \param a the first media type
- * \param pjsip_media_type b
+ * \param b the second media type
  * \retval 1 Media types are equal
  * \retval 0 Media types are not equal
  */
@@ -1138,7 +1138,7 @@ void ast_sip_header_to_security_mechanism(const pjsip_generic_string_hdr *hdr,
 /*!
  * \brief Initialize security mechanism vector from string of security mechanisms.
  *
- * \param security_mechanisms Pointer to vector of security mechanisms to initialize.
+ * \param security_mechanism Pointer to vector of security mechanisms to initialize.
  * \param value String of security mechanisms as defined in RFC 3329.
  * \retval 0 Success
  * \retval non-zero Failure
@@ -1176,7 +1176,7 @@ void ast_sip_security_mechanisms_vector_destroy(struct ast_sip_security_mechanis
  *
  * \param security_mechanism Pointer-pointer to the security mechanism to allocate.
  * \param value The security mechanism string as defined in RFC 3329 (section 2.2)
- * \param ... in the form <mechanism_name>;q=<q_value>;<mechanism_parameters>
+ * \param ... in the form \<mechanism_name>;q=\<q_value>;\<mechanism_parameters>
  * \retval 0 Success
  * \retval non-zero Failure
  */
@@ -3618,7 +3618,7 @@ int ast_sip_set_id_connected_line(struct pjsip_rx_data *rdata, struct ast_party_
  * \param rdata
  * \param id ID structure to fill
  * \param default_id Default ID structure with data to use (for non-trusted endpoints)
- * \param trusted_inbound Whether or not the endpoint is trusted (controls whether PAI or RPID can be used)
+ * \param trust_inbound Whether or not the endpoint is trusted (controls whether PAI or RPID can be used)
  *
  * \retval -1 on failure, 0 on success
  */
@@ -3996,15 +3996,27 @@ const pj_str_t *ast_sip_pjsip_uri_get_username(pjsip_uri *uri);
 const pj_str_t *ast_sip_pjsip_uri_get_hostname(pjsip_uri *uri);
 
 /*!
- * \brief Get the other_param portion of the pjsip_uri
+ * \brief Find an 'other' SIP/SIPS URI parameter by name
  * \since 16.28.0
  *
- * \param uri The pjsip_uri to get hte other_param from
+ * A convenience function to find a named parameter from a SIP/SIPS URI. This
+ * function will not find the following standard SIP/SIPS URI parameters which
+ * are stored separately by PJSIP:
+ *
+ * \li `user`
+ * \li `method`
+ * \li `transport`
+ * \li `ttl`
+ * \li `lr`
+ * \li `maddr`
+ *
+ * \param uri The pjsip_uri to get the parameter from
+ * \param param_str The name of the parameter to find
  *
  * \note This function will check what kind of URI it receives and return
- * the other_param based off of that
+ * the parameter based off of that
  *
- * \return other_param or NULL if not present
+ * \return Find parameter or NULL if not present
  */
 struct pjsip_param *ast_sip_pjsip_uri_get_other_param(pjsip_uri *uri, const pj_str_t *param_str);
 

include/asterisk/res_stir_shaken.h

@@ -156,7 +156,7 @@ struct ast_stir_shaken_payload *ast_stir_shaken_verify2(const char *header, cons
  * \param signature The payload signature
  * \param algorithm The signature algorithm
  * \param public_cert_url The public key URL
- * \param failure_code Additional failure information
+ * \param failure Additional failure information
  * \param profile The stir_shaken_profile
  *
  * \retval ast_stir_shaken_payload on success

include/asterisk/time.h

@@ -255,9 +255,9 @@ struct timeval ast_double2tv(double _td),
 
 /*!
  * \brief Returns a double corresponding to the number of seconds
- * in the timeval _tv.
+ * in the timeval \c tv.
  *
- * \param _tv A pointer to a timeval structure.
+ * \param tv A pointer to a timeval structure.
  * \returns A double containing the number of seconds.
  *
  * This is the inverse of ast_double2tv().

include/asterisk/xml.h

@@ -191,10 +191,10 @@ struct ast_xml_ns *ast_xml_find_namespace(struct ast_xml_doc *doc, struct ast_xm
 
 /*!
  * \brief Find a direct child element by name.
- * \param parent_node This is the parent node to search.
+ * \param _parent_node This is the parent node to search.
- * \param name Node name to find.
+ * \param _name Node name to find.
- * \param attrname attribute name to match (if NULL it won't be matched).
+ * \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).
+ * \param _attrvalue attribute value to match (if NULL it won't be matched).
  * \retval NULL if not found.
  * \return The node on success.
  */
@@ -371,7 +371,7 @@ void ast_xslt_close(struct ast_xslt_doc *xslt);
  * \brief Apply an XSLT stylesheet to an XML document
  *
  * \param xslt    XSLT stylesheet to apply.
- * \param xml     XML document the stylesheet will be applied to.
+ * \param doc     XML document the stylesheet will be applied to.
  * \param params  An array of name value pairs to pass as parameters
  *                The array must terminate with a NULL sentinel.
  *                Example:  { "name1", "value1", "name2", "value2", NULL }
@@ -383,11 +383,11 @@ struct ast_xml_doc *ast_xslt_apply(struct ast_xslt_doc *xslt, struct ast_xml_doc
 /*!
  * \brief Save the results of applying a stylesheet to a string
  *
- * \param buffer[out]  A pointer to a char * to receive the address of the result string.
+ * \param[out] buffer  A pointer to a char * to receive the address of the result string.
  *                     The buffer must be freed with ast_xml_free_text().
- * \param length[out]  A pointer to an int to receive the result string length.
+ * \param[out] length  A pointer to an int to receive the result string length.
- * \param result       The result document from ast_xslt_apply.
+ * \param      result  The result document from ast_xslt_apply.
- * \param xslt         The stylesheet that was applied.
+ * \param      xslt    The stylesheet that was applied.
  *
  * \return 0 on success, any other value on failure.
  */

main/bridge_basic.c

@@ -1397,7 +1397,7 @@ static const char *get_transfer_context(struct ast_channel *transferer, const ch
  * \brief Determine the transfer extension to use.
  *
  * \param transferer Channel initiating the transfer.
- * \param extension User supplied extension if available.  May be NULL.
+ * \param exten User supplied extension if available.  May be NULL.
  *
  * \return The extension to use for the transfer.
  */

res/res_aeap/transaction.h

@@ -105,7 +105,7 @@ int aeap_transaction_result(struct aeap_transaction *tsx);
  *
  * Stops the transaction timer, but does not end/stop the transaction itself
  *
- * \param transaction A transaction to cancel the timer on
+ * \param tsx A transaction to cancel the timer on
  *
  * \returns 0 if canceled, non zero otherwise
  */
@@ -114,7 +114,7 @@ int aeap_transaction_cancel_timer(struct aeap_transaction *tsx);
 /*!
  * \brief Retrieve the user object associated with the transaction
  *
- * \param transaction A transaction object
+ * \param tsx A transaction object
  *
  * \returns A user object, or NULL if non associated
  */

res/res_aeap/transport.h

@@ -166,8 +166,6 @@ int aeap_transport_is_connected(struct aeap_transport *transport);
  * \brief Destroy a transport
  *
  * \param transport The transport to destroy
- *
- * \returns 0 on success, or -1 on error
  */
 void aeap_transport_destroy(struct aeap_transport *transport);
 

res/res_geolocation/geoloc_eprofile.c

@@ -808,15 +808,15 @@ struct ast_geoloc_eprofile *ast_geoloc_eprofile_create_from_pidf(
  * \internal
  * \brief Create an common, intermediate XML document to pass to the outgoing XSLT process
  *
- * \param eprofile    The eprofile
+ * \param element_name The name of the top-level XML element to create
- * \param chan        The channel to resolve variables against
+ * \param eprofile     The eprofile
- * \param ref_string  A reference string for error messages
+ * \param chan         The channel to resolve variables against
- * \return            An XML doc
+ * \param ref_string   A reference string for error messages
+ * \return             An XML doc
  *
  * \note Given that the document is simple and static, it was easier to just
  * create the elements in a string buffer and call ast_xml_read_memory()
  * at the end instead of creating
- *
  */
 static struct ast_xml_node *geoloc_eprofile_to_intermediate(const char *element_name, struct ast_geoloc_eprofile *eprofile,
 	struct ast_channel *chan, const char *ref_string)
@@ -846,8 +846,8 @@ static struct ast_xml_node *geoloc_eprofile_to_intermediate(const char *element_
 
 	pidf_node = ast_xml_new_node(element_name);
 	if (!pidf_node) {
-		SCOPE_EXIT_LOG_RTN_VALUE(NULL, LOG_ERROR, "%s: Unable to create 'pidf' XML node\n",
+		SCOPE_EXIT_LOG_RTN_VALUE(NULL, LOG_ERROR, "%s: Unable to create '%s' XML node\n",
-			ref_string);
+			ref_string, element_name);
 	}
 
 	loc_node = ast_xml_new_child(pidf_node, "location-info");

res/res_pjsip/pjsip_transport_events.c

@@ -50,7 +50,7 @@ struct transport_monitor_notifier {
 
 /*! \brief Structure for transport to be monitored */
 struct transport_monitor {
-	/*! \brief Key <ipaddr>:<port> */
+	/*! \brief Key \<ipaddr>:\<port> */
 	char key[IP6ADDR_COLON_PORT_BUFLEN];
 	/*! \brief The underlying PJSIP transport */
 	pjsip_transport *transport;

res/res_pjsip_pubsub.c

@@ -945,6 +945,8 @@ static struct resource_list *retrieve_resource_list(const char *resource, const
  * \param resource The name of the resource for this tree node.
  * \param visited The vector of resources that have been visited.
  * \param full_state if allocating a list, indicate whether full state is requested in notifications.
+ * \param display_name the display name to include with this tree node.
+ *
  * \retval NULL Allocation failure.
  * \retval non-NULL The newly-allocated tree_node
  */

res/res_rtp_asterisk.c

@@ -6103,8 +6103,9 @@ static void update_lost_stats(struct ast_rtp *rtp, unsigned int lost_packets)
  * The tallied score is based upon recommendations and formulas from ITU-T G.107,
  * ITU-T G.109, ITU-T G.113, and other various internet sources.
  *
+ * \param instance RTP instance
  * \param normdevrtt The average round trip time
- * \param rxjitter The smoothed jitter
+ * \param normdev_rxjitter The smoothed jitter
  * \param stdev_rxjitter The jitter standard deviation value
  * \param normdev_rxlost The average number of packets lost since last check
  *

res/res_speech_aeap.c

@@ -80,6 +80,7 @@ static struct ast_json *custom_fields_to_params(const struct ast_variable *varia
  * receiving a response the returned result is guaranteed to be pass/fail based upon
  * a response handler's result.
  *
+ * \param aeap Pointer to an Asterisk external application object
  * \param name The name of the request to send
  * \param json The core json request data
  * \param data Optional user data to associate with request/response
@@ -87,7 +88,7 @@ static struct ast_json *custom_fields_to_params(const struct ast_variable *varia
  * \returns 0 on success, -1 on error
  */
 static int speech_aeap_send_request(struct ast_aeap *aeap, const char *name,
-	struct ast_json *json, void *obj)
+	struct ast_json *json, void *data)
 {
 	/*
 	 * Wait for a response. Also since we're blocking,
@@ -96,7 +97,7 @@ static int speech_aeap_send_request(struct ast_aeap *aeap, const char *name,
 	struct ast_aeap_tsx_params tsx_params = {
 		.timeout = 1000,
 		.wait = 1,
-		.obj = obj,
+		.obj = data,
 	};
 
 	/* "steals" the json ref */
@@ -116,7 +117,9 @@ static int speech_aeap_send_request(struct ast_aeap *aeap, const char *name,
  *
  * Basic structure of the JSON message to send:
  *
- *   { param: [<param>, ...] }
+ \verbatim
+ { param: [<param>, ...] }
+ \endverbatim
  *
  * \param speech The speech engine
  * \param param The name of the parameter to retrieve
@@ -146,7 +149,9 @@ struct speech_param {
  *
  * Basic structure of the JSON message to send:
  *
- *   { params: { <name> : <value> }  }
+ \verbatim
+ { params: { <name> : <value> }  }
+ \endverbatim
  *
  * \param speech The speech engine
  * \param name The name of the parameter to set
@@ -238,13 +243,15 @@ static int handle_results(struct ast_aeap *aeap, struct ast_json_iter *iter,
  *
  * Basic structure of the expected JSON message to received:
  *
- *   {
+ \verbatim
- *     response: "get"
+ {
- *     "params" : { <name>: <value> | [ <results> ] }
+   response: "get"
- *   }
+   "params" : { <name>: <value> | [ <results> ] }
+ }
+ \endverbatim
  *
- * \param speech The speech engine
+ * \param aeap Pointer to an Asterisk external application object
- * \param param The name of the parameter to retrieve
+ * \param message The received message
  * \param data User data passed to the response handler
  *
  * \returns 0 on success, -1 on error
@@ -351,17 +358,19 @@ static struct ast_aeap_params speech_aeap_params = {
  *
  * Basic structure of the JSON message to send:
  *
- *   {
+ \verbatim
- *     "request": "setup"
+ {
- *     "codecs": [
+   "request": "setup"
- *         {
+   "codecs": [
- *             "name": <name>,
+       {
- *             "attributes": { <name>: <value>, ..., }
+           "name": <name>,
- *         },
+           "attributes": { <name>: <value>, ..., }
- *         ...,
+       },
- *     ],
+       ...,
- *     "params": { <name>: <value>, ..., }
+   ],
- *   }
+   "params": { <name>: <value>, ..., }
+ }
+ \endverbatim
  *
  * \param speech The speech engine
  * \param format The format codec to use

res/res_stir_shaken.c

@@ -604,6 +604,7 @@ static int stir_shaken_verify_signature(const char *msg, const char *signature,
  *
  * \param public_cert_url The public cert URL
  * \param path The path to download the file to
+ * \param acl The ACL to use for cURL (if not NULL)
  *
  * \retval NULL on failure
  * \retval full path filename on success
@@ -641,6 +642,7 @@ static char *run_curl(const char *public_cert_url, const char *path, const struc
  * \param public_cert_url The public cert URL
  * \param path The path to download the file to
  * \param curl Flag signaling if we have run CURL or not
+ * \param acl The ACL to use for cURL (if not NULL)
  *
  * \retval NULL on failure
  * \retval full path filename on success