From bae495601a5f08c8327b7f5753d3a85bd10c1ea7 Mon Sep 17 00:00:00 2001
From: Alexander Traud <pabstraud@compuserve.com>
Date: Tue, 16 Nov 2021 10:55:03 +0100
Subject: [PATCH] res_pjsip: Fix for Doxygen.
ASTERISK-29747
Change-Id: Ic7a1e9453f805a6264fe86c96b7d18b87b376084
---
include/asterisk/res_pjsip.h | 67 ++++++-------
include/asterisk/res_pjsip_cli.h | 6 +-
include/asterisk/res_pjsip_presence_xml.h | 2 +-
include/asterisk/res_pjsip_pubsub.h | 7 +-
include/asterisk/res_pjsip_session.h | 8 +-
include/asterisk/res_pjsip_session_caps.h | 2 +-
res/res_pjsip/config_global.c | 2 -
res/res_pjsip/config_transport.c | 2 +-
res/res_pjsip/include/res_pjsip_private.h | 6 +-
res/res_pjsip/pjsip_distributor.c | 2 -
res/res_pjsip/pjsip_transport_events.c | 2 -
res/res_pjsip_authenticator_digest.c | 3 +-
res/res_pjsip_caller_id.c | 5 +-
res/res_pjsip_history.c | 14 +--
res/res_pjsip_messaging.c | 95 +++++++++++--------
res/res_pjsip_outbound_authenticator_digest.c | 2 +-
res/res_pjsip_outbound_registration.c | 4 -
res/res_pjsip_path.c | 4 +-
res/res_pjsip_publish_asterisk.c | 6 +-
res/res_pjsip_pubsub.c | 8 +-
res/res_pjsip_registrar.c | 5 +-
res/res_pjsip_sdp_rtp.c | 2 +-
res/res_pjsip_session.c | 5 +-
res/res_pjsip_stir_shaken.c | 3 +-
24 files changed, 125 insertions(+), 137 deletions(-)
diff --git a/include/asterisk/res_pjsip.h b/include/asterisk/res_pjsip.h
index 9c1594dd7c..049b5d9fe5 100644
--- a/include/asterisk/res_pjsip.h
+++ b/include/asterisk/res_pjsip.h
@@ -351,8 +351,7 @@ enum ast_sip_contact_status_type {
/*!
* \brief A contact's status.
*
- * \detail Maintains a contact's current status and round trip time
- * if available.
+ * Maintains a contact's current status and round trip time if available.
*/
struct ast_sip_contact_status {
AST_DECLARE_STRING_FIELDS(
@@ -583,8 +582,8 @@ enum ast_sip_call_codec_pref {
* \brief Returns true if the preference is set in the parameter
* \since 18.0.0
*
- * \param param A ast_flags struct with one or more of enum ast_sip_call_codec_pref set
- * \param codec_pref The last component of one of the enum values
+ * \param __param A ast_flags struct with one or more of enum ast_sip_call_codec_pref set
+ * \param __codec_pref The last component of one of the enum values
* \retval 1 if the enum value is set
* \retval 0 if not
*/
@@ -967,7 +966,7 @@ int ast_sip_auth_vector_init(struct ast_sip_auth_vector *vector, const char *aut
/*!
* \brief Free contents of an auth vector.
*
- * \param array Vector whose contents are to be freed
+ * \param vector Vector whose contents are to be freed
*/
void ast_sip_auth_vector_destroy(struct ast_sip_auth_vector *vector);
@@ -1122,7 +1121,7 @@ void ast_sip_unregister_authenticator(struct ast_sip_authenticator *auth);
* An outbound authenticator is responsible for creating responses to
* authentication challenges by remote endpoints.
*
- * \param auth The authenticator to register
+ * \param outbound_auth The authenticator to register
* \retval 0 Success
* \retval -1 Failure
*/
@@ -1892,7 +1891,7 @@ struct ast_sip_sched_task;
*
* \returns Pointer to \ref ast_sip_sched_task ao2 object which must be dereferenced when done.
*
- * \paragraph Serialization
+ * \par Serialization
*
* Specifying a serializer guarantees serialized execution but NOT specifying a serializer
* may still result in tasks being effectively serialized if the thread pool is busy.
@@ -1900,18 +1899,18 @@ struct ast_sip_sched_task;
* That happens automatically (see below). It's to prevent the task from running at the same
* time as other work using the same serializer, whether or not it's being run by the scheduler.
*
- * \paragraph Interval
+ * \par Interval
*
* The interval is used to calculate the next time the task should run. There are two models.
*
* \ref AST_SIP_SCHED_TASK_PERIODIC specifies that the invocations of the task occur at the
- * specific interval. That is, every \ref "interval" milliseconds, regardless of how long the task
- * takes. If the task takes longer than \ref interval, it will be scheduled at the next available
- * multiple of \ref interval. For example: If the task has an interval of 60 seconds and the task
+ * specific interval. That is, every \p interval milliseconds, regardless of how long the task
+ * takes. If the task takes longer than \p interval, it will be scheduled at the next available
+ * multiple of \p interval. For example: If the task has an interval of 60 seconds and the task
* takes 70 seconds, the next invocation will happen at 120 seconds.
*
* \ref AST_SIP_SCHED_TASK_DELAY specifies that the next invocation of the task should start
- * at \ref interval milliseconds after the current invocation has finished.
+ * at \p interval milliseconds after the current invocation has finished.
*
*/
struct ast_sip_sched_task *ast_sip_schedule_task(struct ast_taskprocessor *serializer,
@@ -1966,7 +1965,7 @@ int ast_sip_sched_task_get_times(struct ast_sip_sched_task *schtd,
* \param[out] last_end Pointer to a timeval structure to contain the time when last ended
* \param[out] interval Pointer to an int to contain the interval in ms
* \param[out] time_left Pointer to an int to contain the ms left to the next run
- * \param[out] last_end Pointer to a timeval structure to contain the next run time
+ * \param[out] next_start Pointer to a timeval structure to contain the next run time
* \retval 0 Success
* \retval -1 Failure
* \note Any of the pointers can be NULL if you don't need them.
@@ -2001,7 +2000,7 @@ int ast_sip_sched_task_get_times_by_name(const char *name,
* \param[out] last_end Pointer to a timeval structure to contain the time when last ended
* \param[out] interval Pointer to an int to contain the interval in ms
* \param[out] time_left Pointer to an int to contain the ms left to the next run
- * \param[out] last_end Pointer to a timeval structure to contain the next run time
+ * \param[out] next_start Pointer to a timeval structure to contain the next run time
* \retval 0 Success
* \retval -1 Failure
* \note Any of the pointers can be NULL if you don't need them.
@@ -2053,6 +2052,7 @@ int ast_sip_sched_is_task_running_by_name(const char *name);
* \since 13.9.0
*
* \param schtd The task structure pointer
+ * \param name, maxlen
* \retval 0 success
* \retval 1 failure
*/
@@ -2146,7 +2146,7 @@ pjsip_dialog *ast_sip_create_dialog_uas_locked(const struct ast_sip_endpoint *en
* \brief General purpose method for creating an rdata structure using specific information
* \since 13.15.0
*
- * \param rdata[out] The rdata structure that will be populated
+ * \param[out] rdata The rdata structure that will be populated
* \param packet A SIP message
* \param src_name The source IP address of the message
* \param src_port The source port of the message
@@ -2165,7 +2165,7 @@ int ast_sip_create_rdata_with_contact(pjsip_rx_data *rdata, char *packet,
/*!
* \brief General purpose method for creating an rdata structure using specific information
*
- * \param rdata[out] The rdata structure that will be populated
+ * \param[out] rdata The rdata structure that will be populated
* \param packet A SIP message
* \param src_name The source IP address of the message
* \param src_port The source port of the message
@@ -2247,7 +2247,7 @@ int ast_sip_send_request(pjsip_tx_data *tdata, struct pjsip_dialog *dlg,
*
* \param tdata The request to send
* \param endpoint Optional. If specified, the out-of-dialog request is sent to the endpoint.
- * \param timeout. If non-zero, after the timeout the transaction will be terminated
+ * \param timeout If non-zero, after the timeout the transaction will be terminated
* and the callback will be called with the PJSIP_EVENT_TIMER type.
* \param token Data to be passed to the callback upon receipt of out-of-dialog response.
* \param callback Callback to be called upon receipt of out-of-dialog response.
@@ -2275,7 +2275,7 @@ int ast_sip_send_out_of_dialog_request(pjsip_tx_data *tdata,
* \param rdata The rdata from the incoming request.
* \param st_code The response code to transmit.
* \param contact The contact with which this request is associated.
- * \param[out] tdata The newly-created response
+ * \param[out] p_tdata The newly-created response
*
* The provided contact is attached to tdata with its reference bumped, but will
* not survive for the entire lifetime of tdata since the contact is cleaned up
@@ -2297,7 +2297,7 @@ int ast_sip_create_response(const pjsip_rx_data *rdata, int st_code,
*
* \param res_addr The response address for this response
* \param tdata The response to send
- * \param endpoint The ast_sip_endpoint associated with this response
+ * \param sip_endpoint The ast_sip_endpoint associated with this response
*
* \retval 0 Success
* \retval -1 Failure
@@ -2313,7 +2313,7 @@ int ast_sip_send_response(pjsip_response_addr *res_addr, pjsip_tx_data *tdata, s
*
* \param rdata The request that is being responded to
* \param tdata The response to send
- * \param endpoint The ast_sip_endpoint associated with this response
+ * \param sip_endpoint The ast_sip_endpoint associated with this response
*
* \since 13.4.0
*
@@ -2433,7 +2433,8 @@ int ast_sip_add_body(pjsip_tx_data *tdata, const struct ast_sip_body *body);
* add each part to the SIP message.
*
* \param tdata The message to add the body to
- * \param bodies The parts of the body to add
+ * \param bodies The message bodies to add
+ * \param num_bodies The parts of the body to add
* \retval 0 Success
* \retval -1 Failure
*/
@@ -2446,7 +2447,7 @@ int ast_sip_add_body_multipart(pjsip_tx_data *tdata, const struct ast_sip_body *
* a body if it currently exists, it appends data to an existing body.
*
* \param tdata The message to append the body to
- * \param body The string to append to the end of the current body
+ * \param body_text The string to append to the end of the current body
* \retval 0 Success
* \retval -1 Failure
*/
@@ -2546,6 +2547,7 @@ int ast_sip_retrieve_auths(const struct ast_sip_auth_vector *auths, struct ast_s
*/
void ast_sip_cleanup_auths(struct ast_sip_auth *auths[], size_t num_auths);
+AST_VECTOR(ast_sip_auth_objects_vector, struct ast_sip_auth *);
/*!
* \brief Retrieve relevant SIP auth structures from sorcery as a vector
*
@@ -2555,17 +2557,16 @@ void ast_sip_cleanup_auths(struct ast_sip_auth *auths[], size_t num_auths);
* \retval 0 Success
* \retval -1 Number of auth objects found is less than the number of names supplied.
*
- * \WARNING The number of auth objects retrieved may be less than the
+ * \warning The number of auth objects retrieved may be less than the
* number of auth ids supplied if auth objects couldn't be found for
* some of them.
*
- * \NOTE Since the ref count on all auth objects returned has been
+ * \note Since the ref count on all auth objects returned has been
* bumped, you must call ast_sip_cleanup_auth_objects_vector() to decrement
* the ref count on all of the auth objects in the vector,
* then call AST_VECTOR_FREE() on the vector itself.
*
*/
-AST_VECTOR(ast_sip_auth_objects_vector, struct ast_sip_auth *);
int ast_sip_retrieve_auths_vector(const struct ast_sip_auth_vector *auth_ids,
struct ast_sip_auth_objects_vector *auth_objects);
@@ -2832,7 +2833,7 @@ void ast_sip_unregister_endpoint_formatter(struct ast_sip_endpoint_formatter *ob
* \brief Converts a sorcery object to a string of object properties.
*
* \param obj the sorcery object to convert
- * \param str the string buffer to write the object data
+ * \param buf the string buffer to write the object data
* \retval 0 Success, non-zero on failure
*/
int ast_sip_sorcery_object_to_ami(const void *obj, struct ast_str **buf);
@@ -2841,7 +2842,7 @@ int ast_sip_sorcery_object_to_ami(const void *obj, struct ast_str **buf);
* \brief Formats the endpoint and sends over AMI.
*
* \param endpoint the endpoint to format and send
- * \param endpoint ami AMI variable container
+ * \param ami AMI variable container
* \param count the number of formatters operated on
* \retval 0 Success, otherwise non-zero on error
*/
@@ -2992,8 +2993,6 @@ struct ast_sip_supplement {
* Similarly, a module could reject an incoming request if desired.
*
* \param supplement The supplement to register
- * \retval 0 Success
- * \retval -1 Failure
*/
void ast_sip_register_supplement(struct ast_sip_supplement *supplement);
@@ -3133,7 +3132,6 @@ char *ast_sip_get_default_voicemail_extension(void);
*
* \param[out] realm The default realm
* \param size The buffer size of realm
- * \return nothing
*/
void ast_sip_get_default_realm(char *realm, size_t size);
@@ -3146,7 +3144,6 @@ void ast_sip_get_default_realm(char *realm, size_t size);
*
* \param[out] from_user The default from user
* \param size The buffer size of from_user
- * \return nothing
*/
void ast_sip_get_default_from_user(char *from_user, size_t size);
@@ -3570,8 +3567,6 @@ enum ast_transport_monitor_reg ast_sip_transport_monitor_register_replace(pjsip_
*
* \note The data object passed into the original register will have its reference count
* automatically decremented.
- *
- * \return Nothing
*/
void ast_sip_transport_monitor_unregister(pjsip_transport *transport,
ast_transport_monitor_shutdown_cb cb, void *data, ast_transport_monitor_data_matcher matches);
@@ -3588,8 +3583,6 @@ void ast_sip_transport_monitor_unregister(pjsip_transport *transport,
*
* \note The data object passed into the original register will have its reference count
* automatically decremented.
- *
- * \return Nothing
*/
void ast_sip_transport_monitor_unregister_all(ast_transport_monitor_shutdown_cb cb,
void *data, ast_transport_monitor_data_matcher matches);
@@ -3606,8 +3599,6 @@ struct ast_sip_tpmgr_state_callback {
* \since 13.18.0
*
* \param element What we are registering.
- *
- * \return Nothing
*/
void ast_sip_transport_state_register(struct ast_sip_tpmgr_state_callback *element);
@@ -3616,8 +3607,6 @@ void ast_sip_transport_state_register(struct ast_sip_tpmgr_state_callback *eleme
* \since 13.18.0
*
* \param element What we are unregistering.
- *
- * \return Nothing
*/
void ast_sip_transport_state_unregister(struct ast_sip_tpmgr_state_callback *element);
diff --git a/include/asterisk/res_pjsip_cli.h b/include/asterisk/res_pjsip_cli.h
index c2535218ac..36b59b2847 100644
--- a/include/asterisk/res_pjsip_cli.h
+++ b/include/asterisk/res_pjsip_cli.h
@@ -73,7 +73,6 @@ struct ast_sip_cli_formatter_entry {
/*!
* \brief Registers a CLI formatter.
*
- * \param name The name of the formatter, usually the sorcery object type.
* \param formatter An ao2_callback_fn that outputs the formatted data.
* \retval 0 Success, non-zero on failure
*/
@@ -82,7 +81,7 @@ int ast_sip_register_cli_formatter(struct ast_sip_cli_formatter_entry *formatter
/*!
* \brief Unregisters a CLI formatter.
*
- * \param name The name of the formatter, usually the sorcery object type.
+ * \param formatter The name of the formatter, usually the sorcery object type.
* \retval 0 Success, non-zero on failure
*/
int ast_sip_unregister_cli_formatter(struct ast_sip_cli_formatter_entry *formatter);
@@ -99,7 +98,8 @@ struct ast_sip_cli_formatter_entry *ast_sip_lookup_cli_formatter(const char *nam
* \brief Prints a sorcery object's ast_variable list
*
* \param obj The sorcery object
- * \param arg The ast_sip_cli_context.
+ * \param arg The ast_sip_cli_context
+ * \param flags
* \retval 0 Success, non-zero on failure
*/
int ast_sip_cli_print_sorcery_objectset(void *obj, void *arg, int flags);
diff --git a/include/asterisk/res_pjsip_presence_xml.h b/include/asterisk/res_pjsip_presence_xml.h
index 60235ca94f..7d3d9b7a75 100644
--- a/include/asterisk/res_pjsip_presence_xml.h
+++ b/include/asterisk/res_pjsip_presence_xml.h
@@ -70,6 +70,7 @@ void ast_sip_sanitize_xml(const char *input, char *output, size_t len);
* \param[out] pidfstate
* \param[out] pidfnote
* \param[out] local_state
+ * \param notify_early_inuse_ringing
*/
void ast_sip_presence_exten_state_to_str(int state, char **statestring,
char **pidfstate, char **pidfnote, enum ast_sip_pidf_state *local_state,
@@ -113,7 +114,6 @@ pj_xml_node *ast_sip_presence_xml_create_node(pj_pool_t *pool,
* \param attr_name Name of attribute to find
* \param[out] node Node that was found or created
* \param[out] attr Attribute that was found or created
- * \return The found attribute
*/
void ast_sip_presence_xml_find_node_attr(pj_pool_t* pool,
pj_xml_node *parent, const char *node_name, const char *attr_name,
diff --git a/include/asterisk/res_pjsip_pubsub.h b/include/asterisk/res_pjsip_pubsub.h
index 4309a099e7..354b0b2506 100644
--- a/include/asterisk/res_pjsip_pubsub.h
+++ b/include/asterisk/res_pjsip_pubsub.h
@@ -346,7 +346,7 @@ struct ast_sip_subscription_handler {
* When a subscriber wishes to create a subscription, it may call this function
* to allocate resources and to send the initial SUBSCRIBE out.
*
- * \param subscriber The subscriber that is making the request.
+ * \param handler The subscriber that is making the request.
* \param endpoint The endpoint to whome the SUBSCRIBE will be sent.
* \param resource The resource to place in the SUBSCRIBE's Request-URI.
*/
@@ -742,7 +742,7 @@ void ast_sip_pubsub_unregister_body_generator(struct ast_sip_pubsub_body_generat
* for a given content type if a primary body supplement for that content type
* has already been registered.
*
- * \param generator Body generator to register
+ * \param supplement Body generator to register
* \retval 0 Success
* \retval -1 Failure
*/
@@ -752,7 +752,7 @@ int ast_sip_pubsub_register_body_supplement(struct ast_sip_pubsub_body_supplemen
* \since 13.0.0
* \brief Unregister a body generator with the pubsub core.
*
- * \param generator Body generator to unregister
+ * \param supplement Body generator to unregister
*/
void ast_sip_pubsub_unregister_body_supplement(struct ast_sip_pubsub_body_supplement *supplement);
@@ -773,7 +773,6 @@ const char *ast_sip_subscription_get_body_subtype(struct ast_sip_subscription *s
* \brief Alert the pubsub core that the subscription is ready for destruction
*
* \param sub The subscription that is complete
- * \return Nothing
*/
void ast_sip_subscription_destroy(struct ast_sip_subscription *sub);
diff --git a/include/asterisk/res_pjsip_session.h b/include/asterisk/res_pjsip_session.h
index e2ea64ea59..49e6007915 100644
--- a/include/asterisk/res_pjsip_session.h
+++ b/include/asterisk/res_pjsip_session.h
@@ -493,7 +493,7 @@ struct ast_sip_channel_pvt *ast_sip_channel_pvt_alloc(void *pvt, struct ast_sip_
*
* \param endpoint The endpoint that this session communicates with
* \param contact The contact associated with this session
- * \param inv_session The PJSIP INVITE session data
+ * \param inv The PJSIP INVITE session data
* \param rdata INVITE request received (NULL if for outgoing allocation)
*/
struct ast_sip_session *ast_sip_session_alloc(struct ast_sip_endpoint *endpoint,
@@ -506,8 +506,6 @@ struct ast_sip_session *ast_sip_session_alloc(struct ast_sip_endpoint *endpoint,
* \param session Which session to suspend the serializer.
*
* \note No channel locks can be held while calling without risk of deadlock.
- *
- * \return Nothing
*/
void ast_sip_session_suspend(struct ast_sip_session *session);
@@ -516,8 +514,6 @@ void ast_sip_session_suspend(struct ast_sip_session *session);
* \since 12.7.0
*
* \param session Which session to unsuspend the serializer.
- *
- * \return Nothing
*/
void ast_sip_session_unsuspend(struct ast_sip_session *session);
@@ -734,7 +730,6 @@ int ast_sip_session_refresh(struct ast_sip_session *session,
*
* \param session The session on which the answer will be updated
* \param on_sdp_creation Callback called when SDP is created
- * \param generate_new_sdp Boolean to indicate if a new SDP should be created
* \retval 0 Successfully updated the SDP answer
* \retval -1 Failure to updated the SDP answer
*/
@@ -859,6 +854,7 @@ struct ast_sip_session_media *ast_sip_session_media_state_add(struct ast_sip_ses
/*!
* \brief Save a media stats.
*
+ * \param sip_session Session on which to save active media state for
* \param media_state The media state to save
*/
void ast_sip_session_media_stats_save(struct ast_sip_session *sip_session, struct ast_sip_session_media_state *media_state);
diff --git a/include/asterisk/res_pjsip_session_caps.h b/include/asterisk/res_pjsip_session_caps.h
index 0d7020ff76..5c8b7469b9 100644
--- a/include/asterisk/res_pjsip_session_caps.h
+++ b/include/asterisk/res_pjsip_session_caps.h
@@ -31,7 +31,7 @@ struct ast_sip_session;
* \param remote The "remote" capabilities
* \param local The "local" capabilities
* \param media_type The media type
- * \param codec_prefs One or more of enum ast_sip_call_codec_pref
+ * \param codec_pref One or more of enum ast_sip_call_codec_pref
*
* \retval A pointer to the joint capabilities (which may be empty).
* NULL will be returned only if no memory was available to allocate the structure.
diff --git a/res/res_pjsip/config_global.c b/res/res_pjsip/config_global.c
index 1d44222501..5bc1cc6704 100644
--- a/res/res_pjsip/config_global.c
+++ b/res/res_pjsip/config_global.c
@@ -564,8 +564,6 @@ static int overload_trigger_to_str(const void *obj, const intptr_t *args, char *
* \param sorcery Instance being observed.
* \param object_type Name of object being observed.
* \param reloaded Non-zero if the object is being reloaded.
- *
- * \return Nothing
*/
static void global_loaded_observer(const char *name, const struct ast_sorcery *sorcery, const char *object_type, int reloaded)
{
diff --git a/res/res_pjsip/config_transport.c b/res/res_pjsip/config_transport.c
index 502ad5b1ce..db6207656c 100644
--- a/res/res_pjsip/config_transport.c
+++ b/res/res_pjsip/config_transport.c
@@ -1197,6 +1197,7 @@ static pj_ssl_cipher cipher_name_to_id(const char *name)
}
#endif
+#if defined(PJ_HAS_SSL_SOCK) && PJ_HAS_SSL_SOCK != 0
/*!
* \internal
* \brief Add a new cipher to the transport's cipher list array.
@@ -1207,7 +1208,6 @@ static pj_ssl_cipher cipher_name_to_id(const char *name)
* \retval 0 on success.
* \retval -1 on error.
*/
-#if defined(PJ_HAS_SSL_SOCK) && PJ_HAS_SSL_SOCK != 0
static int transport_cipher_add(struct ast_sip_transport_state *state, const char *name)
{
pj_ssl_cipher cipher;
diff --git a/res/res_pjsip/include/res_pjsip_private.h b/res/res_pjsip/include/res_pjsip_private.h
index f6333bf3a0..dcb821cedc 100644
--- a/res/res_pjsip/include/res_pjsip_private.h
+++ b/res/res_pjsip/include/res_pjsip_private.h
@@ -178,16 +178,12 @@ int ast_sip_destroy_sorcery_global(void);
/*!
* \internal
* \brief Initialize global headers support
- *
- * \return Nothing
*/
void ast_sip_initialize_global_headers(void);
/*!
* \internal
* \brief Destroy global headers support
- *
- * \return Nothing
*/
void ast_sip_destroy_global_headers(void);
@@ -383,7 +379,7 @@ int ast_sip_will_uri_survive_restart(pjsip_sip_uri *uri, struct ast_sip_endpoint
* for that period of time, it also prevents issues if the transport
* disconnects while we're still trying to process a response.
* (Attack mitigation)
- * 3. If enabled by global/keep_alive_interval, it sends '\r\n'
+ * 3. If enabled by global/keep_alive_interval, it sends '\\r\\n'
* keepalives on reliable transports at the interval specified.
*
* \retval -1 Failure
diff --git a/res/res_pjsip/pjsip_distributor.c b/res/res_pjsip/pjsip_distributor.c
index 72ed35b35e..ea8fb02124 100644
--- a/res/res_pjsip/pjsip_distributor.c
+++ b/res/res_pjsip/pjsip_distributor.c
@@ -1219,8 +1219,6 @@ static struct ast_sorcery_observer global_observer = {
* \internal
* \brief Shutdown the serializers in the distributor pool.
* \since 13.10.0
- *
- * \return Nothing
*/
static void distributor_pool_shutdown(void)
{
diff --git a/res/res_pjsip/pjsip_transport_events.c b/res/res_pjsip/pjsip_transport_events.c
index 5eb9868f1f..4df1d5e6e6 100644
--- a/res/res_pjsip/pjsip_transport_events.c
+++ b/res/res_pjsip/pjsip_transport_events.c
@@ -121,8 +121,6 @@ static void transport_monitor_dtor(void *vdoomed)
*
* \param transports Active transports container
* \param transport Which transport to do callbacks for.
- *
- * \return Nothing
*/
static void transport_state_do_reg_callbacks(struct ao2_container *transports, pjsip_transport *transport)
{
diff --git a/res/res_pjsip_authenticator_digest.c b/res/res_pjsip_authenticator_digest.c
index 231a7e5aab..2cdbe6eff5 100644
--- a/res/res_pjsip_authenticator_digest.c
+++ b/res/res_pjsip_authenticator_digest.c
@@ -199,7 +199,8 @@ static pj_status_t digest_lookup(pj_pool_t *pool, const pj_str_t *realm,
* is from the same source that the nonce was calculated for. Including the realm
* ensures that multiple challenges to the same request have different nonces.
*
- * \param A UNIX timestamp expressed as a string
+ * \param nonce
+ * \param timestamp A UNIX timestamp expressed as a string
* \param rdata The incoming request
* \param realm The realm for which authentication should occur
*/
diff --git a/res/res_pjsip_caller_id.c b/res/res_pjsip_caller_id.c
index f1c89ee7d0..96e2cf96e4 100644
--- a/res/res_pjsip_caller_id.c
+++ b/res/res_pjsip_caller_id.c
@@ -467,6 +467,7 @@ static void caller_id_incoming_response(struct ast_sip_session *session, pjsip_r
* \internal
* \brief Create an identity header for an outgoing message
* \param hdr_name The name of the header to create
+ * \param base
* \param tdata The message to place the header on
* \param id The identification information for the new header
* \return newly-created header
@@ -543,6 +544,7 @@ static void add_privacy_header(pjsip_tx_data *tdata, const struct ast_party_id *
/*!
* \internal
* \brief Add a P-Asserted-Identity header to an outbound message
+ * \param session The session on which communication is happening
* \param tdata The message to add the header to
* \param id The identification information used to populate the header
*/
@@ -679,6 +681,7 @@ static void add_privacy_params(pjsip_tx_data *tdata, pjsip_fromto_hdr *hdr, cons
/*!
* \internal
* \brief Add a Remote-Party-ID header to an outbound message
+ * \param session The session on which communication is happening
* \param tdata The message to add the header to
* \param id The identification information used to populate the header
*/
@@ -737,7 +740,7 @@ static void add_rpid_header(const struct ast_sip_session *session, pjsip_tx_data
*
* \param session The session on which we will be sending the message
* \param tdata The outbound message
- * \param The identity information to place on the message
+ * \param id The identity information to place on the message
*/
static void add_id_headers(const struct ast_sip_session *session, pjsip_tx_data *tdata, const struct ast_party_id *id)
{
diff --git a/res/res_pjsip_history.c b/res/res_pjsip_history.c
index e4b784dca4..ca86f242b6 100644
--- a/res/res_pjsip_history.c
+++ b/res/res_pjsip_history.c
@@ -73,12 +73,9 @@ struct pjsip_history_entry {
pjsip_msg *msg;
};
-/*! \brief Mutex that protects \ref vector_history */
+/*! \brief Mutex that protects \c vector_history */
AST_MUTEX_DEFINE_STATIC(history_lock);
-/*! \brief The one and only history that we've captured */
-static AST_VECTOR(vector_history_t, struct pjsip_history_entry *) vector_history;
-
struct expression_token;
/*! \brief An operator that we understand in an expression */
@@ -161,6 +158,9 @@ struct expression_token {
/*! \brief Log level for history output */
static int log_level = -1;
+/*! \brief The one and only history that we've captured */
+static AST_VECTOR(vector_history_t, struct pjsip_history_entry *) vector_history;
+
/*!
* \brief Operator callback for determining equality
*/
@@ -542,7 +542,7 @@ static struct expression_token *expression_token_free(struct expression_token *t
* \param value The value/operator/result to pack into the token
*
* \retval NULL on failure
- * \retval \c expression_token on success
+ * \retval expression_token on success
*/
static struct expression_token *expression_token_alloc(enum expression_token_type token_type, void *value)
{
@@ -772,7 +772,7 @@ static void clear_history_entry_cb(struct pjsip_history_entry *entry)
}
/*!
- * \brief Remove all entries from \ref vector_history
+ * \brief Remove all entries from \c vector_history
*
* This must be called from a registered PJSIP thread
*/
@@ -794,7 +794,7 @@ static int clear_history_entries(void *obj)
* polish notation expression, which is a queue of tokens that can be easily
* parsed.
*
- * \params a The CLI arguments provided by the User, containing the infix expression
+ * \param a The CLI arguments provided by the User, containing the infix expression
*
* \retval NULL error
* \retval expression_token A 'queue' of expression tokens in RPN
diff --git a/res/res_pjsip_messaging.c b/res/res_pjsip_messaging.c
index 571a7c9584..f0db27cec6 100644
--- a/res/res_pjsip_messaging.c
+++ b/res/res_pjsip_messaging.c
@@ -278,10 +278,13 @@ static int insert_user_in_contact_uri(const char *to, const char *endpoint_name,
* \brief Get endpoint and URI when the destination is only a single token
*
* "to" could be one of the following:
- * endpoint_name
- * hostname
+ * \verbatim
+ endpoint_name
+ hostname
+ * \endverbatim
*
* \param to Destination specified in MessageSend
+ * \param destination
* \param uri Pointer to URI variable. Must be freed by caller
* \return endpoint
*/
@@ -341,18 +344,21 @@ static struct ast_sip_endpoint *handle_single_token(const char *to, char *destin
* \brief Get endpoint and URI when the destination contained a '/'
*
* "to" could be one of the following:
- * endpoint/aor
- * endpoint/<sip[s]:host>
- * endpoint/<sip[s]:user@host>
- * endpoint/"Bob" <sip[s]:host>
- * endpoint/"Bob" <sip[s]:user@host>
- * endpoint/sip[s]:host
- * endpoint/sip[s]:user@host
- * endpoint/host
- * endpoint/user@host
+ * \verbatim
+ endpoint/aor
+ endpoint/<sip[s]:host>
+ endpoint/<sip[s]:user@host>
+ endpoint/"Bob" <sip[s]:host>
+ endpoint/"Bob" <sip[s]:user@host>
+ endpoint/sip[s]:host
+ endpoint/sip[s]:user@host
+ endpoint/host
+ endpoint/user@host
+ * \endverbatim
*
* \param to Destination specified in MessageSend
* \param uri Pointer to URI variable. Must be freed by caller
+ * \param destination, slash, atsign, scheme
* \return endpoint
*/
static struct ast_sip_endpoint *handle_slash(const char *to, char *destination, char **uri,
@@ -490,16 +496,19 @@ static struct ast_sip_endpoint *handle_slash(const char *to, char *destination,
/*!
* \internal
- * \brief Get endpoint and URI when the destination contained a '@' but no '/' or scheme
+ * \brief Get endpoint and URI when the destination contained a '\@' but no '/' or scheme
*
* "to" could be one of the following:
- * <sip[s]:user@host>
- * "Bob" <sip[s]:user@host>
- * sip[s]:user@host
- * user@host
+ * \verbatim
+ <sip[s]:user@host>
+ "Bob" <sip[s]:user@host>
+ sip[s]:user@host
+ user@host
+ * \endverbatim
*
* \param to Destination specified in MessageSend
* \param uri Pointer to URI variable. Must be freed by caller
+ * \param destination, slash, atsign, scheme
* \return endpoint
*/
static struct ast_sip_endpoint *handle_atsign(const char *to, char *destination, char **uri,
@@ -564,35 +573,45 @@ static struct ast_sip_endpoint *handle_atsign(const char *to, char *destination,
* Expects the given 'to' to be in one of the following formats:
* Why we allow so many is a mystery.
*
- * Basic:
- * endpoint - We'll get URI from the default aor/contact
- * endpoint/aor - We'll get the URI from the specific aor/contact
- * endpoint@domain - We toss the domain part and just use the endpoint
+ * Basic:
+ *
+ * endpoint : We'll get URI from the default aor/contact
+ * endpoint/aor : We'll get the URI from the specific aor/contact
+ * endpoint@domain : We toss the domain part and just use the endpoint
*
* These all use the endpoint and specified URI:
- * endpoint/<sip[s]:host>
- * endpoint/<sip[s]:user@host>
- * endpoint/"Bob" <sip[s]:host>
- * endpoint/"Bob" <sip[s]:user@host>
- * endpoint/sip[s]:host
- * endpoint/sip[s]:user@host
- * endpoint/host
- * endpoint/user@host
+ * \verbatim
+ endpoint/<sip[s]:host>
+ endpoint/<sip[s]:user@host>
+ endpoint/"Bob" <sip[s]:host>
+ endpoint/"Bob" <sip[s]:user@host>
+ endpoint/sip[s]:host
+ endpoint/sip[s]:user@host
+ endpoint/host
+ endpoint/user@host
+ \endverbatim
*
* These all use the default endpoint and specified URI:
- * <sip[s]:host>
- * <sip[s]:user@host>
- * "Bob" <sip[s]:host>
- * "Bob" <sip[s]:user@host>
- * sip[s]:host
- * sip[s]:user@host
+ * \verbatim
+ <sip[s]:host>
+ <sip[s]:user@host>
+ "Bob" <sip[s]:host>
+ "Bob" <sip[s]:user@host>
+ sip[s]:host
+ sip[s]:user@host
+ \endverbatim
*
* These use the default endpoint and specified host:
- * host
- * user@host
+ * \verbatim
+ host
+ user@host
+ \endverbatim
*
* This form is similar to a dialstring:
- * PJSIP/user@endpoint
+ * \verbatim
+ PJSIP/user@endpoint
+ \endverbatim
+ *
* In this case, the user will be added to the endpoint contact's URI.
* If the contact URI already has a user, it will be replaced.
*
@@ -1203,7 +1222,7 @@ static void update_content_type(pjsip_tx_data *tdata, struct ast_msg *msg, struc
* \internal
* \brief Send a MESSAGE
*
- * \param mdata The outbound message data structure
+ * \param data The outbound message data structure
*
* \return 0: success, -1: failure
*
diff --git a/res/res_pjsip_outbound_authenticator_digest.c b/res/res_pjsip_outbound_authenticator_digest.c
index 55781e9603..e6702b4df2 100644
--- a/res/res_pjsip_outbound_authenticator_digest.c
+++ b/res/res_pjsip_outbound_authenticator_digest.c
@@ -118,7 +118,7 @@ static int is_digest_algorithm_supported(pjsip_www_authenticate_hdr *auth_hdr)
* In the end, we'll have accumulated a list of credentials we can pass to
* pjproject that it can use to add Authentication headers to a request.
*
- * \NOTE: Neither we nor pjproject can currently handle digest algorithms
+ * \note: Neither we nor pjproject can currently handle digest algorithms
* other than MD5. We don't even have a place for it in the ast_sip_auth
* object. For this reason, we just skip processing any Authenticate
* header that's not MD5. When we support the others, we'll move the
diff --git a/res/res_pjsip_outbound_registration.c b/res/res_pjsip_outbound_registration.c
index 2ee7cca433..1422d47fb9 100644
--- a/res/res_pjsip_outbound_registration.c
+++ b/res/res_pjsip_outbound_registration.c
@@ -933,8 +933,6 @@ static int reregister_immediately_cb(void *obj)
* \param obj What is needed to initiate a reregister attempt.
*
* \note Normally executed by the pjsip monitor thread.
- *
- * \return Nothing
*/
static void registration_transport_shutdown_cb(void *obj)
{
@@ -2393,8 +2391,6 @@ static int check_state(void *obj, void *arg, int flags)
* \param sorcery Instance being observed.
* \param object_type Name of object being observed.
* \param reloaded Non-zero if the object is being reloaded.
- *
- * \return Nothing
*/
static void registration_loaded_observer(const char *name, const struct ast_sorcery *sorcery, const char *object_type, int reloaded)
{
diff --git a/res/res_pjsip_path.c b/res/res_pjsip_path.c
index 9f48009e54..5eb3d49e05 100644
--- a/res/res_pjsip_path.c
+++ b/res/res_pjsip_path.c
@@ -103,8 +103,8 @@ static struct ast_sip_aor *find_aor(struct ast_sip_endpoint *endpoint, pjsip_uri
/*!
* \brief Get the path string associated with this contact and tdata
*
- * \param endpoint The endpoint from which to pull associated path data
- * \param contact_uri The URI identifying the associated contact
+ * \param pool
+ * \param contact The URI identifying the associated contact
* \param path_str The place to store the retrieved path information
*
* \retval zero on success
diff --git a/res/res_pjsip_publish_asterisk.c b/res/res_pjsip_publish_asterisk.c
index 5fea3bf7a8..a88f9cacab 100644
--- a/res/res_pjsip_publish_asterisk.c
+++ b/res/res_pjsip_publish_asterisk.c
@@ -166,9 +166,8 @@ static const struct ast_datastore_info asterisk_mwi_publisher_state_datastore =
/*!
* \brief Callback function for device state events
- * \param ast_event
* \param data void pointer to ast_client structure
- * \return void
+ * \param sub, msg
*/
static void asterisk_publisher_devstate_cb(void *data, struct stasis_subscription *sub, struct stasis_message *msg)
{
@@ -225,9 +224,8 @@ static void asterisk_publisher_devstate_cb(void *data, struct stasis_subscriptio
/*!
* \brief Callback function for mailbox state events
- * \param ast_event
* \param data void pointer to ast_client structure
- * \return void
+ * \param sub, msg
*/
static void asterisk_publisher_mwistate_cb(void *data, struct stasis_subscription *sub, struct stasis_message *msg)
{
diff --git a/res/res_pjsip_pubsub.c b/res/res_pjsip_pubsub.c
index e62582f383..31394e28a8 100644
--- a/res/res_pjsip_pubsub.c
+++ b/res/res_pjsip_pubsub.c
@@ -597,8 +597,6 @@ static int sub_tree_subscription_terminate_cb(void *data)
* \param data What subscription needs to be terminated.
*
* \note Normally executed by the pjsip monitor thread.
- *
- * \return Nothing
*/
static void sub_tree_transport_cb(void *data)
{
@@ -927,7 +925,7 @@ 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 if allocating a list, indicate whether full state is requested in notifications.
+ * \param full_state if allocating a list, indicate whether full state is requested in notifications.
* \retval NULL Allocation failure.
* \retval non-NULL The newly-allocated tree_node
*/
@@ -1456,7 +1454,8 @@ static struct sip_subscription_tree *allocate_subscription_tree(struct ast_sip_e
* \param resource The requested resource in the SUBSCRIBE request
* \param generator The body generator to use in leaf subscriptions
* \param tree The resource tree on which the subscription tree is based
- * \param dlg_status[out] The result of attempting to create a dialog.
+ * \param[out] dlg_status The result of attempting to create a dialog
+ * \param persistence
*
* \retval NULL Could not create the subscription tree
* \retval non-NULL The root of the created subscription tree
@@ -2021,6 +2020,7 @@ static int sip_subscription_send_request(struct sip_subscription_tree *sub_tree,
* elements refer to later parts in the multipart body.
*
* \param pool PJLIB allocation pool
+ * \param rlmi
* \param cid Content-ID header of the resource
* \param resource_name Name of the resource
* \param resource_uri URI of the resource
diff --git a/res/res_pjsip_registrar.c b/res/res_pjsip_registrar.c
index 605c0fa2f5..9c999c15cf 100644
--- a/res/res_pjsip_registrar.c
+++ b/res/res_pjsip_registrar.c
@@ -364,8 +364,6 @@ static int register_contact_transport_remove_cb(void *data)
* \param data What contact needs to be removed.
*
* \note Normally executed by the pjsip monitor thread.
- *
- * \return Nothing
*/
static void register_contact_transport_shutdown_cb(void *data)
{
@@ -562,8 +560,7 @@ static int vec_contact_add(void *obj, void *arg, int flags)
*
* \param contacts Container of unmodified contacts that could remove.
* \param to_remove Maximum number of contacts to remove.
- *
- * \return Nothing
+ * \param response_contacts, remove_existing
*/
static void remove_excess_contacts(struct ao2_container *contacts, struct ao2_container *response_contacts,
unsigned int to_remove, unsigned int remove_existing)
diff --git a/res/res_pjsip_sdp_rtp.c b/res/res_pjsip_sdp_rtp.c
index d422f01794..a3bc462942 100644
--- a/res/res_pjsip_sdp_rtp.c
+++ b/res/res_pjsip_sdp_rtp.c
@@ -961,7 +961,7 @@ static enum ast_sip_session_media_encryption get_media_encryption_type(pj_str_t
* \brief Checks whether the encryption offered in SDP is compatible with the endpoint's configuration
* \internal
*
- * \param endpoint_encryption Media encryption configured for the endpoint
+ * \param endpoint Media encryption configured for the endpoint
* \param stream pjmedia_sdp_media stream description
*
* \retval AST_SIP_MEDIA_TRANSPORT_INVALID on encryption mismatch
diff --git a/res/res_pjsip_session.c b/res/res_pjsip_session.c
index 2fb5b46087..787fd9552a 100644
--- a/res/res_pjsip_session.c
+++ b/res/res_pjsip_session.c
@@ -1742,6 +1742,7 @@ static void set_from_header(struct ast_sip_session *session)
* \internal
* \brief Validate a media state
*
+ * \param session_name For log messages
* \param state Media state
*
* \retval 1 The media state is valid
@@ -1827,7 +1828,7 @@ end:
* \param delayed_pending_state The pending media state at the time the resuest was queued
* \param delayed_active_state The active media state at the time the resuest was queued
* \param current_active_state The current active media state
- * \param run_validation Whether to run validation on the resulting media state or not
+ * \param run_post_validation Whether to run validation on the resulting media state or not
*
* \returns New merged topology or NULL if there's an error
*
@@ -3582,8 +3583,6 @@ int ast_sip_session_defer_termination(struct ast_sip_session *session)
* \since 13.5.0
*
* \param session Which session to stop the timer.
- *
- * \return Nothing
*/
static void sip_session_defer_termination_stop_timer(struct ast_sip_session *session)
{
diff --git a/res/res_pjsip_stir_shaken.c b/res/res_pjsip_stir_shaken.c
index 1bf2528394..27aa4d8caf 100644
--- a/res/res_pjsip_stir_shaken.c
+++ b/res/res_pjsip_stir_shaken.c
@@ -61,7 +61,8 @@ static char *get_attestation_from_payload(const char *json_str)
/*!
* \brief Compare the caller ID from the INVITE with the one in the payload
*
- * \param json_str The JSON string represntation of the payload
+ * \param caller_id
+ * \param json_str The JSON string representation of the payload
*
* \retval -1 on failure
* \retval 0 on success
--
GitLab