[Asterisk-code-review] res_pjsip: Fix for Doxygen. (asterisk[18])

Alexander Traud asteriskteam at digium.com
Tue Nov 16 04:10:08 CST 2021


Alexander Traud has uploaded this change for review. ( https://gerrit.asterisk.org/c/asterisk/+/17480 )


Change subject: res_pjsip: Fix for Doxygen.
......................................................................

res_pjsip: Fix for Doxygen.

ASTERISK-29747

Change-Id: Ic7a1e9453f805a6264fe86c96b7d18b87b376084
---
M include/asterisk/res_pjsip.h
M include/asterisk/res_pjsip_cli.h
M include/asterisk/res_pjsip_presence_xml.h
M include/asterisk/res_pjsip_pubsub.h
M include/asterisk/res_pjsip_session.h
M include/asterisk/res_pjsip_session_caps.h
M res/res_pjsip/config_global.c
M res/res_pjsip/config_transport.c
M res/res_pjsip/include/res_pjsip_private.h
M res/res_pjsip/pjsip_distributor.c
M res/res_pjsip/pjsip_transport_events.c
M res/res_pjsip_authenticator_digest.c
M res/res_pjsip_caller_id.c
M res/res_pjsip_history.c
M res/res_pjsip_messaging.c
M res/res_pjsip_outbound_authenticator_digest.c
M res/res_pjsip_outbound_registration.c
M res/res_pjsip_path.c
M res/res_pjsip_publish_asterisk.c
M res/res_pjsip_pubsub.c
M res/res_pjsip_registrar.c
M res/res_pjsip_sdp_rtp.c
M res/res_pjsip_session.c
M res/res_pjsip_stir_shaken.c
24 files changed, 125 insertions(+), 137 deletions(-)



  git pull ssh://gerrit.asterisk.org:29418/asterisk refs/changes/80/17480/1

diff --git a/include/asterisk/res_pjsip.h b/include/asterisk/res_pjsip.h
index 9c1594d..049b5d9 100644
--- a/include/asterisk/res_pjsip.h
+++ b/include/asterisk/res_pjsip.h
@@ -351,8 +351,7 @@
 /*!
  * \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 @@
  * \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 @@
 /*!
  * \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 @@
  * 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 @@
  *
  * \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 @@
  * 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 @@
  * \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 @@
  * \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 @@
  * \since 13.9.0
  *
  * \param schtd The task structure pointer
+ * \param name, maxlen
  * \retval 0 success
  * \retval 1 failure
  */
@@ -2146,7 +2146,7 @@
  * \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 @@
 /*!
  * \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 @@
  *
  * \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 @@
  * \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 @@
  *
  * \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 @@
  *
  * \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 @@
  * 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 @@
  * 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 @@
  */
 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 @@
  * \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 @@
  * \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 @@
  * \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 @@
  * 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 @@
  *
  * \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 @@
  *
  * \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 @@
  *
  * \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 @@
  *
  * \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 @@
  * \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 @@
  * \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 c253521..36b59b2 100644
--- a/include/asterisk/res_pjsip_cli.h
+++ b/include/asterisk/res_pjsip_cli.h
@@ -73,7 +73,6 @@
 /*!
  * \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 @@
 /*!
  * \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 @@
  * \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 60235ca..7d3d9b7 100644
--- a/include/asterisk/res_pjsip_presence_xml.h
+++ b/include/asterisk/res_pjsip_presence_xml.h
@@ -70,6 +70,7 @@
  * \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 @@
  * \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 4309a09..354b0b2 100644
--- a/include/asterisk/res_pjsip_pubsub.h
+++ b/include/asterisk/res_pjsip_pubsub.h
@@ -346,7 +346,7 @@
  * 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 @@
  * 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 @@
  * \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 @@
  * \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 e2ea64e..49e6007 100644
--- a/include/asterisk/res_pjsip_session.h
+++ b/include/asterisk/res_pjsip_session.h
@@ -493,7 +493,7 @@
  *
  * \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 @@
  * \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 @@
  * \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 @@
  *
  * \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 @@
 /*!
  * \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 0d7020f..5c8b746 100644
--- a/include/asterisk/res_pjsip_session_caps.h
+++ b/include/asterisk/res_pjsip_session_caps.h
@@ -31,7 +31,7 @@
  * \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 1d44222..5bc1cc6 100644
--- a/res/res_pjsip/config_global.c
+++ b/res/res_pjsip/config_global.c
@@ -564,8 +564,6 @@
  * \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 502ad5b..db62076 100644
--- a/res/res_pjsip/config_transport.c
+++ b/res/res_pjsip/config_transport.c
@@ -1197,6 +1197,7 @@
 }
 #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 @@
  * \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 f6333bf..dcb821c 100644
--- a/res/res_pjsip/include/res_pjsip_private.h
+++ b/res/res_pjsip/include/res_pjsip_private.h
@@ -178,16 +178,12 @@
 /*!
  * \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 @@
  * 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 72ed35b..ea8fb02 100644
--- a/res/res_pjsip/pjsip_distributor.c
+++ b/res/res_pjsip/pjsip_distributor.c
@@ -1219,8 +1219,6 @@
  * \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 5eb9868..4df1d5e 100644
--- a/res/res_pjsip/pjsip_transport_events.c
+++ b/res/res_pjsip/pjsip_transport_events.c
@@ -121,8 +121,6 @@
  *
  * \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 231a7e5..2cdbe6e 100644
--- a/res/res_pjsip_authenticator_digest.c
+++ b/res/res_pjsip_authenticator_digest.c
@@ -199,7 +199,8 @@
  * 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 3b871cd..287346b 100644
--- a/res/res_pjsip_caller_id.c
+++ b/res/res_pjsip_caller_id.c
@@ -478,6 +478,7 @@
  * \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
@@ -554,6 +555,7 @@
 /*!
  * \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
  */
@@ -690,6 +692,7 @@
 /*!
  * \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
  */
@@ -748,7 +751,7 @@
  *
  * \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 e4b784d..ca86f24 100644
--- a/res/res_pjsip_history.c
+++ b/res/res_pjsip_history.c
@@ -73,12 +73,9 @@
 	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 @@
 /*! \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 @@
  * \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 @@
 }
 
 /*!
- * \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 @@
  * 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 571a7c9..f0db27c 100644
--- a/res/res_pjsip_messaging.c
+++ b/res/res_pjsip_messaging.c
@@ -278,10 +278,13 @@
  * \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 @@
  * \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 at host>
- *		endpoint/"Bob" <sip[s]:host>
- *		endpoint/"Bob" <sip[s]:user at host>
- *		endpoint/sip[s]:host
- *		endpoint/sip[s]:user at host
- *		endpoint/host
- *		endpoint/user at host
+ * \verbatim
+		endpoint/aor
+		endpoint/<sip[s]:host>
+		endpoint/<sip[s]:user at host>
+		endpoint/"Bob" <sip[s]:host>
+		endpoint/"Bob" <sip[s]:user at host>
+		endpoint/sip[s]:host
+		endpoint/sip[s]:user at host
+		endpoint/host
+		endpoint/user at 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 @@
 
 /*!
  * \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 at host>
- *		"Bob" <sip[s]:user at host>
- *		sip[s]:user at host
- *		user at host
+ * \verbatim
+		<sip[s]:user at host>
+		"Bob" <sip[s]:user at host>
+		sip[s]:user at host
+		user at 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 @@
  * 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 at 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 at 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 at host>
- *      endpoint/"Bob" <sip[s]:host>
- *      endpoint/"Bob" <sip[s]:user at host>
- *      endpoint/sip[s]:host
- *      endpoint/sip[s]:user at host
- *      endpoint/host
- *      endpoint/user at host
+ * \verbatim
+        endpoint/<sip[s]:host>
+        endpoint/<sip[s]:user at host>
+        endpoint/"Bob" <sip[s]:host>
+        endpoint/"Bob" <sip[s]:user at host>
+        endpoint/sip[s]:host
+        endpoint/sip[s]:user at host
+        endpoint/host
+        endpoint/user at host
+   \endverbatim
  *
  *   These all use the default endpoint and specified URI:
- *      <sip[s]:host>
- *      <sip[s]:user at host>
- *      "Bob" <sip[s]:host>
- *      "Bob" <sip[s]:user at host>
- *      sip[s]:host
- *      sip[s]:user at host
+ * \verbatim
+        <sip[s]:host>
+        <sip[s]:user at host>
+        "Bob" <sip[s]:host>
+        "Bob" <sip[s]:user at host>
+        sip[s]:host
+        sip[s]:user at host
+   \endverbatim
  *
  *   These use the default endpoint and specified host:
- *      host
- *      user at host
+ * \verbatim
+        host
+        user at host
+   \endverbatim
  *
  *   This form is similar to a dialstring:
- *      PJSIP/user at endpoint
+ * \verbatim
+        PJSIP/user at 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 @@
  * \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 55781e9..e6702b4 100644
--- a/res/res_pjsip_outbound_authenticator_digest.c
+++ b/res/res_pjsip_outbound_authenticator_digest.c
@@ -118,7 +118,7 @@
  * 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 2ee7cca..1422d47 100644
--- a/res/res_pjsip_outbound_registration.c
+++ b/res/res_pjsip_outbound_registration.c
@@ -933,8 +933,6 @@
  * \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 @@
  * \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 9f48009..5eb3d49 100644
--- a/res/res_pjsip_path.c
+++ b/res/res_pjsip_path.c
@@ -103,8 +103,8 @@
 /*!
  * \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 5fea3bf..a88f9ca 100644
--- a/res/res_pjsip_publish_asterisk.c
+++ b/res/res_pjsip_publish_asterisk.c
@@ -166,9 +166,8 @@
 
 /*!
  * \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 @@
 
 /*!
  * \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 e62582f..31394e2 100644
--- a/res/res_pjsip_pubsub.c
+++ b/res/res_pjsip_pubsub.c
@@ -597,8 +597,6 @@
  * \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 @@
  *
  * \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 @@
  * \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 @@
  * 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 605c0fa..9c999c1 100644
--- a/res/res_pjsip_registrar.c
+++ b/res/res_pjsip_registrar.c
@@ -364,8 +364,6 @@
  * \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 @@
  *
  * \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 d422f01..a3bc462 100644
--- a/res/res_pjsip_sdp_rtp.c
+++ b/res/res_pjsip_sdp_rtp.c
@@ -961,7 +961,7 @@
  * \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 2fb5b46..787fd95 100644
--- a/res/res_pjsip_session.c
+++ b/res/res_pjsip_session.c
@@ -1742,6 +1742,7 @@
  * \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 @@
  * \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 @@
  * \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 1bf2528..27aa4d8 100644
--- a/res/res_pjsip_stir_shaken.c
+++ b/res/res_pjsip_stir_shaken.c
@@ -61,7 +61,8 @@
 /*!
  * \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

-- 
To view, visit https://gerrit.asterisk.org/c/asterisk/+/17480
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings

Gerrit-Project: asterisk
Gerrit-Branch: 18
Gerrit-Change-Id: Ic7a1e9453f805a6264fe86c96b7d18b87b376084
Gerrit-Change-Number: 17480
Gerrit-PatchSet: 1
Gerrit-Owner: Alexander Traud <pabstraud at compuserve.com>
Gerrit-MessageType: newchange
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20211116/ed45de1a/attachment-0001.html>


More information about the asterisk-code-review mailing list