[Asterisk-code-review] doxygen: Fix doxygen errors. (asterisk[master])
Sean Bright
asteriskteam at digium.com
Mon Jan 30 15:28:59 CST 2023
Sean Bright has uploaded this change for review. ( https://gerrit.asterisk.org/c/asterisk/+/19882 )
Change subject: doxygen: Fix doxygen errors.
......................................................................
doxygen: Fix doxygen errors.
Change-Id: Ic50e95b4fc10f74ab15416d908e8a87ee8ec2f85
---
M apps/app_mf.c
M include/asterisk/channel.h
M include/asterisk/crypto.h
M include/asterisk/pbx.h
M include/asterisk/res_aeap.h
M include/asterisk/res_aeap_message.h
M include/asterisk/res_geolocation.h
M include/asterisk/res_pjsip.h
M include/asterisk/res_stir_shaken.h
M include/asterisk/time.h
M include/asterisk/xml.h
M main/bridge_basic.c
M res/res_aeap/transaction.h
M res/res_aeap/transport.h
M res/res_geolocation/geoloc_eprofile.c
M res/res_pjsip/pjsip_transport_events.c
M res/res_pjsip_pubsub.c
M res/res_rtp_asterisk.c
M res/res_speech_aeap.c
M res/res_stir_shaken.c
20 files changed, 110 insertions(+), 77 deletions(-)
git pull ssh://gerrit.asterisk.org:29418/asterisk refs/changes/82/19882/1
diff --git a/apps/app_mf.c b/apps/app_mf.c
index cd3320d..5840b56 100644
--- a/apps/app_mf.c
+++ b/apps/app_mf.c
@@ -235,6 +235,7 @@
* \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
diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h
index 2b67bc6..9911436 100644
--- a/include/asterisk/channel.h
+++ b/include/asterisk/channel.h
@@ -2255,8 +2255,8 @@
* \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 duration the duration of a ST, STP, ST2P, or ST3P digit ending in ms
+ * \param durationkp the duration of a KP 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.
diff --git a/include/asterisk/crypto.h b/include/asterisk/crypto.h
index 2a7ecf0..078711f 100644
--- a/include/asterisk/crypto.h
+++ b/include/asterisk/crypto.h
@@ -110,10 +110,10 @@
/*!
* \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 @@
/*!
* \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 @@
* \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 @@
* \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
*/
diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h
index b7a5428..ec752a9 100644
--- a/include/asterisk/pbx.h
+++ b/include/asterisk/pbx.h
@@ -271,9 +271,9 @@
/*!
* \brief Execute an application
*
- * \param c channel to execute on
- * \param app name of app to execute
- * \param data the data passed into the app
+ * \param chan channel to execute on
+ * \param app_name name of app to execute
+ * \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
diff --git a/include/asterisk/res_aeap.h b/include/asterisk/res_aeap.h
index 0a1747e..b4b68cf 100644
--- a/include/asterisk/res_aeap.h
+++ b/include/asterisk/res_aeap.h
@@ -55,7 +55,7 @@
/*!
* \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 @@
/*!
* \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 @@
* 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 @@
* 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.
*
diff --git a/include/asterisk/res_aeap_message.h b/include/asterisk/res_aeap_message.h
index 294039e..1fd5329 100644
--- a/include/asterisk/res_aeap_message.h
+++ b/include/asterisk/res_aeap_message.h
@@ -241,7 +241,6 @@
* \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 @@
* \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
*/
diff --git a/include/asterisk/res_geolocation.h b/include/asterisk/res_geolocation.h
index 0a5a61d..2f88c80 100644
--- a/include/asterisk/res_geolocation.h
+++ b/include/asterisk/res_geolocation.h
@@ -165,7 +165,7 @@
* \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 @@
* \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.
*/
diff --git a/include/asterisk/res_pjsip.h b/include/asterisk/res_pjsip.h
index 5b86d0f..599ec26 100644
--- a/include/asterisk/res_pjsip.h
+++ b/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 dest The destination buffer of at least IP6ADDR_COLON_PORT_BUFLEN bytes
+ * \param _transport The pjsip_transport to use
+ * \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 @@
/*!
* \brief Compare pjsip media types
*
- * \param pjsip_media_type a
- * \param pjsip_media_type b
+ * \param a the first media type
+ * \param b the second media type
* \retval 1 Media types are equal
* \retval 0 Media types are not equal
*/
@@ -1138,7 +1138,7 @@
/*!
* \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 @@
*
* \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 @@
* \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_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);
diff --git a/include/asterisk/res_stir_shaken.h b/include/asterisk/res_stir_shaken.h
index ece99b5..540f988 100644
--- a/include/asterisk/res_stir_shaken.h
+++ b/include/asterisk/res_stir_shaken.h
@@ -156,7 +156,7 @@
* \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
diff --git a/include/asterisk/time.h b/include/asterisk/time.h
index 23ba18f..130084c 100644
--- a/include/asterisk/time.h
+++ b/include/asterisk/time.h
@@ -255,9 +255,9 @@
/*!
* \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().
diff --git a/include/asterisk/xml.h b/include/asterisk/xml.h
index 5c2e9f9..1350444 100644
--- a/include/asterisk/xml.h
+++ b/include/asterisk/xml.h
@@ -191,10 +191,10 @@
/*!
* \brief Find a direct child element by name.
- * \param parent_node This is the parent node to search.
- * \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).
+ * \param _parent_node This is the parent node to search.
+ * \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.
* \return The node on success.
*/
@@ -371,7 +371,7 @@
* \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 @@
/*!
* \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 result The result document from ast_xslt_apply.
- * \param xslt The stylesheet that was applied.
+ * \param[out] length A pointer to an int to receive the result string length.
+ * \param result The result document from ast_xslt_apply.
+ * \param xslt The stylesheet that was applied.
*
* \return 0 on success, any other value on failure.
*/
diff --git a/main/bridge_basic.c b/main/bridge_basic.c
index 115f6a3..96d38e5 100644
--- a/main/bridge_basic.c
+++ b/main/bridge_basic.c
@@ -1397,7 +1397,7 @@
* \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.
*/
diff --git a/res/res_aeap/transaction.h b/res/res_aeap/transaction.h
index 973ba1a..6e48411 100644
--- a/res/res_aeap/transaction.h
+++ b/res/res_aeap/transaction.h
@@ -105,7 +105,7 @@
*
* 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 @@
/*!
* \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
*/
diff --git a/res/res_aeap/transport.h b/res/res_aeap/transport.h
index 622247e..1cd4997 100644
--- a/res/res_aeap/transport.h
+++ b/res/res_aeap/transport.h
@@ -166,8 +166,6 @@
* \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);
diff --git a/res/res_geolocation/geoloc_eprofile.c b/res/res_geolocation/geoloc_eprofile.c
index 09a06c6..3d10d12 100644
--- a/res/res_geolocation/geoloc_eprofile.c
+++ b/res/res_geolocation/geoloc_eprofile.c
@@ -808,15 +808,15 @@
* \internal
* \brief Create an common, intermediate XML document to pass to the outgoing XSLT process
*
- * \param eprofile The eprofile
- * \param chan The channel to resolve variables against
- * \param ref_string A reference string for error messages
- * \return An XML doc
+ * \param element_name The name of the top-level XML element to create
+ * \param eprofile The eprofile
+ * \param chan The channel to resolve variables against
+ * \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 @@
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",
- ref_string);
+ SCOPE_EXIT_LOG_RTN_VALUE(NULL, LOG_ERROR, "%s: Unable to create '%s' XML node\n",
+ ref_string, element_name);
}
loc_node = ast_xml_new_child(pidf_node, "location-info");
diff --git a/res/res_pjsip/pjsip_transport_events.c b/res/res_pjsip/pjsip_transport_events.c
index 0e4705d..130e26c 100644
--- a/res/res_pjsip/pjsip_transport_events.c
+++ b/res/res_pjsip/pjsip_transport_events.c
@@ -50,7 +50,7 @@
/*! \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;
diff --git a/res/res_pjsip_pubsub.c b/res/res_pjsip_pubsub.c
index 26b86cc..9ebd8c2 100644
--- a/res/res_pjsip_pubsub.c
+++ b/res/res_pjsip_pubsub.c
@@ -945,6 +945,8 @@
* \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
*/
diff --git a/res/res_rtp_asterisk.c b/res/res_rtp_asterisk.c
index bd4c1f7..9468ec6 100644
--- a/res/res_rtp_asterisk.c
+++ b/res/res_rtp_asterisk.c
@@ -6103,8 +6103,9 @@
* 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
*
diff --git a/res/res_speech_aeap.c b/res/res_speech_aeap.c
index d81d6e5..1aa8041 100644
--- a/res/res_speech_aeap.c
+++ b/res/res_speech_aeap.c
@@ -80,6 +80,7 @@
* 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 @@
* \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 @@
struct ast_aeap_tsx_params tsx_params = {
.timeout = 1000,
.wait = 1,
- .obj = obj,
+ .obj = data,
};
/* "steals" the json ref */
@@ -116,7 +117,9 @@
*
* 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 @@
*
* 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 @@
*
* Basic structure of the expected JSON message to received:
*
- * {
- * response: "get"
- * "params" : { <name>: <value> | [ <results> ] }
- * }
+ \verbatim
+ {
+ response: "get"
+ "params" : { <name>: <value> | [ <results> ] }
+ }
+ \endverbatim
*
- * \param speech The speech engine
- * \param param The name of the parameter to retrieve
+ * \param aeap Pointer to an Asterisk external application object
+ * \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 @@
*
* Basic structure of the JSON message to send:
*
- * {
- * "request": "setup"
- * "codecs": [
- * {
- * "name": <name>,
- * "attributes": { <name>: <value>, ..., }
- * },
- * ...,
- * ],
- * "params": { <name>: <value>, ..., }
- * }
+ \verbatim
+ {
+ "request": "setup"
+ "codecs": [
+ {
+ "name": <name>,
+ "attributes": { <name>: <value>, ..., }
+ },
+ ...,
+ ],
+ "params": { <name>: <value>, ..., }
+ }
+ \endverbatim
*
* \param speech The speech engine
* \param format The format codec to use
diff --git a/res/res_stir_shaken.c b/res/res_stir_shaken.c
index 52480ff..a4eae5b 100644
--- a/res/res_stir_shaken.c
+++ b/res/res_stir_shaken.c
@@ -604,6 +604,7 @@
*
* \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 @@
* \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
--
To view, visit https://gerrit.asterisk.org/c/asterisk/+/19882
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings
Gerrit-Project: asterisk
Gerrit-Branch: master
Gerrit-Change-Id: Ic50e95b4fc10f74ab15416d908e8a87ee8ec2f85
Gerrit-Change-Number: 19882
Gerrit-PatchSet: 1
Gerrit-Owner: Sean Bright <sean at seanbright.com>
Gerrit-MessageType: newchange
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20230130/86cf304a/attachment-0001.html>
More information about the asterisk-code-review
mailing list