[Asterisk-code-review] res: Fix for Doxygen. (asterisk[16])

Friendly Automation asteriskteam at digium.com
Fri Dec 3 10:43:23 CST 2021


Friendly Automation has submitted this change. ( https://gerrit.asterisk.org/c/asterisk/+/17512 )

Change subject: res: Fix for Doxygen.
......................................................................

res: Fix for Doxygen.

These are the remaining issues found in /res.

ASTERISK-29761

Change-Id: I572e6019c422780dde5ce8448b6c85c77af6046d
---
M include/asterisk/calendar.h
M include/asterisk/http_websocket.h
M include/asterisk/phoneprov.h
M include/asterisk/res_hep.h
M include/asterisk/res_mwi_external.h
M include/asterisk/res_pjproject.h
M include/asterisk/res_pjsip.h
M include/asterisk/res_pjsip_cli.h
M include/asterisk/statsd.h
M res/ael/ael_lex.c
M res/res_chan_stats.c
M res/res_config_ldap.c
M res/res_config_sqlite3.c
M res/res_crypto.c
M res/res_hep.c
M res/res_http_websocket.c
M res/res_monitor.c
M res/res_mwi_external.c
M res/res_phoneprov.c
M res/res_pjsip/pjsip_resolver.c
M res/res_pjsip_history.c
M res/res_pjsip_mwi.c
M res/res_pjsip_notify.c
M res/res_pjsip_session.c
M res/res_rtp_asterisk.c
M res/res_stasis.c
M res/res_stir_shaken/certificate.h
M res/res_stir_shaken/curl.c
M res/res_stun_monitor.c
M res/res_xmpp.c
M res/snmp/agent.h
M res/stasis/app.h
32 files changed, 104 insertions(+), 147 deletions(-)

Approvals:
  Kevin Harwell: Looks good to me, but someone else must approve
  Benjamin Keith Ford: Looks good to me, approved
  Friendly Automation: Approved for Submit



diff --git a/include/asterisk/calendar.h b/include/asterisk/calendar.h
index 9f89f33..4564c34 100644
--- a/include/asterisk/calendar.h
+++ b/include/asterisk/calendar.h
@@ -152,9 +152,6 @@
 /*! \brief Unregister a new calendar technology
  *
  * \param tech calendar technology to unregister
- *
- * \retval 0 success
- * \retval -1 failure
  */
 void ast_calendar_unregister(struct ast_calendar_tech *tech);
 
diff --git a/include/asterisk/http_websocket.h b/include/asterisk/http_websocket.h
index d5489fa..2a55e60 100644
--- a/include/asterisk/http_websocket.h
+++ b/include/asterisk/http_websocket.h
@@ -127,10 +127,10 @@
 };
 
 /*!
- * \brief Creates a \ref websocket_server
+ * \brief Creates a \ref ast_websocket_server
  *
- * \retval New \ref websocket_server instance
- * \retval \c NULL on error
+ * \return New \ref ast_websocket_server instance
+ * \retval NULL on error
  * \since 12
  */
 AST_OPTIONAL_API(struct ast_websocket_server *, ast_websocket_server_create, (void), { return NULL; });
@@ -146,7 +146,7 @@
 /*!
  * \brief Allocate a websocket sub-protocol instance
  *
- * \retval An instance of \ref ast_websocket_protocol on success
+ * \return An instance of \ref ast_websocket_protocol on success
  * \retval NULL on error
  * \since 13.5.0
  */
@@ -169,7 +169,7 @@
  * \param protocol The sub-protocol to register. Note that this must
  * be allocated using /ref ast_websocket_sub_protocol_alloc.
  *
- * \note This method is reference stealing. It will steal the reference to \ref protocol
+ * \note This method is reference stealing. It will steal the reference to \p protocol
  * on success.
  *
  * \retval 0 success
@@ -192,6 +192,7 @@
 /*!
  * \brief Add a sub-protocol handler to the given server.
  *
+ * \param server The server to add the sub-protocol to
  * \param name Name of the sub-protocol to register
  * \param callback Callback called when a new connection requesting the sub-protocol is established
  *
@@ -208,7 +209,7 @@
  * \param protocol The sub-protocol to register. Note that this must
  * be allocated using /ref ast_websocket_sub_protocol_alloc.
  *
- * \note This method is reference stealing. It will steal the reference to \ref protocol
+ * \note This method is reference stealing. It will steal the reference to \p protocol
  * on success.
  *
  * \retval 0 success
@@ -220,6 +221,7 @@
 /*!
  * \brief Remove a sub-protocol handler from the given server.
  *
+ * \param server The server to unregister the sub-protocol from
  * \param name Name of the sub-protocol to unregister
  * \param callback Callback that was previously registered with the sub-protocol
  *
@@ -253,7 +255,7 @@
  * \param ws pointer to the websocket
  * \param buf string buffer to populate with data read from socket
  * \retval -1 on error
- * \retval number of bytes read on success
+ * \return number of bytes read on success
  *
  * \note Once an AST_WEBSOCKET_OPCODE_CLOSE opcode is received the socket will be closed
  */
@@ -332,7 +334,7 @@
 /*!
  * \brief Get the file descriptor for a WebSocket session.
  *
- * \retval file descriptor
+ * \return file descriptor
  *
  * \note You must *not* directly read from or write to this file descriptor. It should only be used for polling.
  */
@@ -355,14 +357,14 @@
 /*!
  * \brief Get the remote address for a WebSocket connected session.
  *
- * \retval ast_sockaddr Remote address
+ * \return Remote address
  */
 AST_OPTIONAL_API(struct ast_sockaddr *, ast_websocket_remote_address, (struct ast_websocket *session), {return NULL;});
 
 /*!
  * \brief Get the local address for a WebSocket connection session.
  *
- * \retval ast_sockaddr Local address
+ * \return Local address
  *
  * \since 13.19.0
  */
@@ -387,7 +389,7 @@
 /*!
  * \brief Get the session ID for a WebSocket session.
  *
- * \retval session id
+ * \return session id
  */
 AST_OPTIONAL_API(const char *, ast_websocket_session_id, (struct ast_websocket *session), { errno = ENOSYS; return NULL;});
 
@@ -414,21 +416,22 @@
 /*!
  * \brief Create, and connect, a websocket client.
  *
- * \detail If the client websocket successfully connects, then the accepted protocol
- *         can be checked via a call to ast_websocket_client_accept_protocol.
+ * If the client websocket successfully connects, then the accepted protocol can be
+ * checked via a call to ast_websocket_client_accept_protocol.
  *
  * \note While connecting this *will* block until a response is
  *       received from the remote host.
- * \note Expected uri form: ws[s]://<address>[:port][/<path>] The address (can be a
- *       host name) and port are parsed out and used to connect to the remote server.
- *       If multiple IPs are returned during address resolution then the first one is
- *       chosen.
+ * \note Expected uri form:
+ *       \verbatim ws[s]://<address>[:port][/<path>] \endverbatim
+ *       The address (can be a host name) and port are parsed out and used to connect
+ *       to the remote server.  If multiple IPs are returned during address
+ *       resolution then the first one is chosen.
  *
  * \param uri uri to connect to
  * \param protocols a comma separated string of supported protocols
  * \param tls_cfg secure websocket credentials
  * \param result result code set on client failure
- * \retval a client websocket.
+ * \return a client websocket.
  * \retval NULL if object could not be created or connected
  * \since 13
  */
@@ -441,7 +444,7 @@
  * \brief Retrieve the server accepted sub-protocol on the client.
  *
  * \param ws the websocket client
- * \retval the accepted client sub-protocol.
+ * \return the accepted client sub-protocol.
  * \since 13
  */
 AST_OPTIONAL_API(const char *, ast_websocket_client_accept_protocol,
diff --git a/include/asterisk/phoneprov.h b/include/asterisk/phoneprov.h
index 24e8cc9..2fad829 100644
--- a/include/asterisk/phoneprov.h
+++ b/include/asterisk/phoneprov.h
@@ -95,7 +95,7 @@
 /*!
  * \brief Adds an extension
  * \param provider_name The name of the provider
- * \param defaults An ast_vat_t linked list of the extension's variables.
+ * \param vars An ast_vat_t linked list of the extension's variables.
  * The list is automatically cloned and it must contain at least MACADDRESS
  * and USERNAME entries.
  *
diff --git a/include/asterisk/res_hep.h b/include/asterisk/res_hep.h
index dba86e8..837baca 100644
--- a/include/asterisk/res_hep.h
+++ b/include/asterisk/res_hep.h
@@ -87,9 +87,9 @@
  * reclaimed.
  *
  * \param payload The payload to send to the HEP capture node
- * \param len     Length of \ref payload
+ * \param len     Length of \p payload
  *
- * \retval A \ref hepv3_capture_info ref counted object on success
+ * \return A \ref hepv3_capture_info ref counted object on success
  * \retval NULL on error
  */
 struct hepv3_capture_info *hepv3_create_capture_info(const void *payload, size_t len);
@@ -102,7 +102,7 @@
  * \ref hepv3_create_capture_info.
  *
  * Once this function is called, it assumes ownership of the
- * \ref capture_info object and steals the reference of the
+ * \p capture_info object and steals the reference of the
  * object. Regardless of success or failure, the calling function
  * should assumed that this function will own the object.
  *
@@ -116,7 +116,7 @@
  *
  * \since 13.10.0
  *
- * \retval The type of UUID the packet should use
+ * \return The type of UUID the packet should use
  */
 enum hep_uuid_type hepv3_get_uuid_type(void);
 
diff --git a/include/asterisk/res_mwi_external.h b/include/asterisk/res_mwi_external.h
index 19385d5..28f38d7 100644
--- a/include/asterisk/res_mwi_external.h
+++ b/include/asterisk/res_mwi_external.h
@@ -47,7 +47,7 @@
  *
  * \param mailbox_id Name of mailbox.
  *
- * \retval object on success.  The object is an ao2 object.
+ * \return object on success.  The object is an ao2 object.
  * \retval NULL on error.
  */
 struct ast_mwi_mailbox_object *ast_mwi_mailbox_alloc(const char *mailbox_id);
@@ -90,7 +90,7 @@
  *
  * \param mailbox What to copy.
  *
- * \retval copy on success.  The object is an ao2 object.
+ * \return copy on success.  The object is an ao2 object.
  * \retval NULL on error.
  */
 struct ast_mwi_mailbox_object *ast_mwi_mailbox_copy(const struct ast_mwi_mailbox_object *mailbox);
@@ -101,8 +101,6 @@
  *
  * \param mailbox Object to set number of new messages.
  * \param num_msgs Number of messages to set.
- *
- * \return Nothing
  */
 void ast_mwi_mailbox_set_msgs_new(struct ast_mwi_mailbox_object *mailbox, unsigned int num_msgs);
 
@@ -112,8 +110,6 @@
  *
  * \param mailbox Object to set number of old messages.
  * \param num_msgs Number of messages to set.
- *
- * \return Nothing
  */
 void ast_mwi_mailbox_set_msgs_old(struct ast_mwi_mailbox_object *mailbox, unsigned int num_msgs);
 
@@ -167,7 +163,7 @@
  *
  * \param mailbox_id Name of mailbox to retrieve.
  *
- * \retval requested mailbox on success.  The object is an ao2 object.
+ * \return requested mailbox on success.  The object is an ao2 object.
  * \retval NULL on error or no mailbox.
  *
  * \note The object must be treated as read-only.
@@ -182,7 +178,7 @@
  *
  * \note The provided regex is treated as extended case sensitive.
  *
- * \retval container of struct ast_mwi_mailbox_object on success.
+ * \return container of struct ast_mwi_mailbox_object on success.
  * \retval NULL on error.
  *
  * \note The objects in the container must be treated as read-only.
@@ -193,7 +189,7 @@
  * \brief Get all external MWI objects.
  * \since 12.1.0
  *
- * \retval container of struct ast_mwi_mailbox_object on success.
+ * \return container of struct ast_mwi_mailbox_object on success.
  * \retval NULL on error.
  *
  * \note The objects in the container must be treated as read-only.
diff --git a/include/asterisk/res_pjproject.h b/include/asterisk/res_pjproject.h
index d195c0f..eee8c4e 100644
--- a/include/asterisk/res_pjproject.h
+++ b/include/asterisk/res_pjproject.h
@@ -59,8 +59,6 @@
  * \note ast_pjproject_log_intercept_begin() and
  * ast_pjproject_log_intercept_end() must always be called
  * in pairs.
- *
- * \return Nothing
  */
 void ast_pjproject_log_intercept_begin(int fd);
 
@@ -71,8 +69,6 @@
  * \note ast_pjproject_log_intercept_begin() and
  * ast_pjproject_log_intercept_end() must always be called
  * in pairs.
- *
- * \return Nothing
  */
 void ast_pjproject_log_intercept_end(void);
 
@@ -83,8 +79,6 @@
  * \param cp Caching pool factory to initialize
  * \param policy Pool factory policy
  * \param max_capacity Total capacity to be retained in the cache.  Zero disables caching.
- *
- * \return Nothing
  */
 void ast_pjproject_caching_pool_init(pj_caching_pool *cp,
 	const pj_pool_factory_policy *policy, pj_size_t max_capacity);
@@ -94,8 +88,6 @@
  * \since 13.21.0
  *
  * \param cp Caching pool factory to destroy
- *
- * \return Nothing
  */
 void ast_pjproject_caching_pool_destroy(pj_caching_pool *cp);
 
diff --git a/include/asterisk/res_pjsip.h b/include/asterisk/res_pjsip.h
index 7e8637c..3fa8dcf 100644
--- a/include/asterisk/res_pjsip.h
+++ b/include/asterisk/res_pjsip.h
@@ -2405,9 +2405,9 @@
  *
  * \note Caller is responsible for freeing the allocated memory.
  *
- * \param dest [out] The destination buffer
+ * \param[out] dest The destination buffer
  * \param src The pj_str_t to copy
- * \retval Number of characters copied or negative value on error
+ * \return Number of characters copied or negative value on error
  */
 int ast_copy_pj_str2(char **dest, const pj_str_t *src);
 
@@ -3388,8 +3388,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);
diff --git a/include/asterisk/res_pjsip_cli.h b/include/asterisk/res_pjsip_cli.h
index 36b59b2..24f92fe 100644
--- a/include/asterisk/res_pjsip_cli.h
+++ b/include/asterisk/res_pjsip_cli.h
@@ -28,7 +28,7 @@
 #define CLI_MAX_TITLE_NAME 8
 #define CLI_INDENT_TO_SPACES(x) ((x * 2) + 1 + CLI_MAX_TITLE_NAME)
 
-/*
+/*!
  * \brief CLI Formatter Context passed to all formatters.
  */
 struct ast_sip_cli_context {
@@ -46,7 +46,7 @@
 	unsigned show_details_only_level_0 : 1;
 };
 
-/*
+/*!
  * \brief CLI Formatter Registry Entry
  */
 struct ast_sip_cli_formatter_entry {
diff --git a/include/asterisk/statsd.h b/include/asterisk/statsd.h
index 1f8468e..c3942c6 100644
--- a/include/asterisk/statsd.h
+++ b/include/asterisk/statsd.h
@@ -56,7 +56,7 @@
  * updating a current value rather than resetting it.
  *
  * \param metric_name String (UTF-8) name of the metric.
- * \param type_str Type of metric to send.
+ * \param metric_type Type of metric to send.
  * \param value Value to send.
  * \param sample_rate Percentage of samples to send.
  * \since 13
@@ -94,7 +94,7 @@
  * ast_statsd_log_sample() for a slightly more convenient interface.
  *
  * \param metric_name String (UTF-8) name of the metric.
- * \param type_str Type of metric to send.
+ * \param metric_type Type of metric to send.
  * \param value Value to send.
  * \param sample_rate Percentage of samples to send.
  * \since 12
diff --git a/res/ael/ael_lex.c b/res/ael/ael_lex.c
index a716a17..04821fe 100644
--- a/res/ael/ael_lex.c
+++ b/res/ael/ael_lex.c
@@ -2990,7 +2990,7 @@
 }
 
 /** Set the current column.
- * @param line_number
+ * @param column_no
  * @param yyscanner The scanner object.
  */
 void ael_yyset_column (int  column_no , yyscan_t yyscanner)
diff --git a/res/res_chan_stats.c b/res/res_chan_stats.c
index dbc79f0..6b79f12 100644
--- a/res/res_chan_stats.c
+++ b/res/res_chan_stats.c
@@ -49,9 +49,6 @@
  * \brief Subscription callback for all channel messages.
  * \param data Data pointer given when creating the subscription.
  * \param sub This subscription.
- * \param topic The topic the message was posted to. This is not necessarily the
- *              topic you subscribed to, since messages may be forwarded between
- *              topics.
  * \param message The message itself.
  */
 static void statsmaker(void *data, struct stasis_subscription *sub,
@@ -81,9 +78,6 @@
  * \brief Router callback for \ref stasis_cache_update messages.
  * \param data Data pointer given when added to router.
  * \param sub This subscription.
- * \param topic The topic the message was posted to. This is not necessarily the
- *              topic you subscribed to, since messages may be forwarded between
- *              topics.
  * \param message The message itself.
  */
 static void updates(void *data, struct stasis_subscription *sub,
@@ -131,9 +125,6 @@
  * \brief Router callback for any message that doesn't otherwise have a route.
  * \param data Data pointer given when added to router.
  * \param sub This subscription.
- * \param topic The topic the message was posted to. This is not necessarily the
- *              topic you subscribed to, since messages may be forwarded between
- *              topics.
  * \param message The message itself.
  */
 static void default_route(void *data, struct stasis_subscription *sub,
diff --git a/res/res_config_ldap.c b/res/res_config_ldap.c
index 3d02c21..a49663a 100644
--- a/res/res_config_ldap.c
+++ b/res/res_config_ldap.c
@@ -98,7 +98,7 @@
 	struct ast_variable *attributes;  /*!< attribute names conversion */
 	struct ast_variable *delimiters;  /*!< the current delimiter is semicolon, so we are not using this variable */
 	AST_LIST_ENTRY(ldap_table_config) entry;
-	/* TODO: Make proxies work */
+	/*! \todo: Make proxies work */
 };
 
 /*! \brief Should be locked before using it
@@ -160,7 +160,8 @@
 	return var;
 }
 
-/*! \brief Count  semicolons in string
+/*!
+ * \brief Count semicolons in string
  * \param somestr - pointer to a string
  *
  * \return number of occurances of the delimiter(semicolon)
@@ -177,7 +178,8 @@
 	return count;
 }
 
-/* \brief Count semicolons in variables
+/*!
+ * \brief Count semicolons in variables
  *
  * takes a linked list of \a ast_variable variables, finds the one with the name variable_value
  * and returns the number of semicolons in the value for that \a ast_variable
@@ -405,7 +407,7 @@
 	int delim_tot_count = 0;
 	int delim_count = 0;
 
-	/* \brief First find the total count
+	/*! \brief First find the total count
 	 */
 	ldap_entry = ldap_first_entry(ldapConn, ldap_result_msg);
 
@@ -432,7 +434,7 @@
 
 	i = 0;
 
-	/* \brief For each static realtime variable we may create several entries in the \a vars array if it's delimited
+	/*! \brief For each static realtime variable we may create several entries in the \a vars array if it's delimited
 	 */
 	for (entry_index = 0; ldap_entry; ) {
 		int pos = 0;
@@ -891,7 +893,7 @@
 
 		ldap_msgfree(ldap_result_msg);
 
-		/*! \TODO get the default variables from the accountBaseDN, not implemented with delimited values
+		/*! \todo get the default variables from the accountBaseDN, not implemented with delimited values
 		 */
 		if (vars) {
 			struct ast_variable **p = vars;
diff --git a/res/res_config_sqlite3.c b/res/res_config_sqlite3.c
index 4d99c79..5dc4784 100644
--- a/res/res_config_sqlite3.c
+++ b/res/res_config_sqlite3.c
@@ -565,7 +565,7 @@
  * of rows returned from a SELECT statement and still process each row
  * independently.
  *
- * \param data user data pointer passed in via sqlite3_exec()
+ * \param arg user data pointer passed in via sqlite3_exec()
  * \param num_columns number of columns in the result
  * \param values array of pointers to column values
  * \param columns array of pointers of to column names
diff --git a/res/res_crypto.c b/res/res_crypto.c
index 7d70665..65ebcc5 100644
--- a/res/res_crypto.c
+++ b/res/res_crypto.c
@@ -161,7 +161,7 @@
  * \param ifd incoming file descriptor
  * \param ofd outgoing file descriptor
  * \param not2
- * \retval key on success.
+ * \return key on success.
  * \retval NULL on failure.
 */
 static struct ast_key *try_load_key(const char *dir, const char *fname, int ifd, int ofd, int *not2)
@@ -487,7 +487,6 @@
  * \brief refresh RSA keys from file
  * \param ifd file descriptor
  * \param ofd file descriptor
- * \return void
 */
 static void crypto_load(int ifd, int ofd)
 {
@@ -546,7 +545,7 @@
  * \param e CLI command
  * \param cmd
  * \param a list of CLI arguments
- * \return CLI_SUCCESS
+ * \retval CLI_SUCCESS
 */
 static char *handle_cli_keys_show(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
 {
@@ -592,7 +591,7 @@
  * \param e CLI command
  * \param cmd
  * \param a list of CLI arguments
- * \return CLI_SUCCESS
+ * \retval CLI_SUCCESS
 */
 static char *handle_cli_keys_init(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
 {
diff --git a/res/res_hep.c b/res/res_hep.c
index 376fc4e..3241801 100644
--- a/res/res_hep.c
+++ b/res/res_hep.c
@@ -144,7 +144,7 @@
 	/*! A KEEP ALIVE TIMER */
 	CHUNK_TYPE_KEEP_ALIVE_TIMER = 0X000D,
 
-	/*! THE \REF CAPTURE_PASSWORD IF DEFINED */
+	/*! THE CAPTURE_PASSWORD IF DEFINED */
 	CHUNK_TYPE_AUTH_KEY = 0X000E,
 
 	/*! THE ONE AND ONLY PAYLOAD */
diff --git a/res/res_http_websocket.c b/res/res_http_websocket.c
index f543b9f..624f20c 100644
--- a/res/res_http_websocket.c
+++ b/res/res_http_websocket.c
@@ -1085,7 +1085,8 @@
 
 /*! \brief Parse the given uri into a path and remote address.
  *
- * Expected uri form: [ws[s]]://<host>[:port][/<path>]
+ * Expected uri form:
+ * \verbatim [ws[s]]://<host>[:port][/<path>] \endverbatim
  *
  * The returned host will contain the address and optional port while
  * path will contain everything after the address/port if included.
diff --git a/res/res_monitor.c b/res/res_monitor.c
index 235dc2d..aba4bbe 100644
--- a/res/res_monitor.c
+++ b/res/res_monitor.c
@@ -299,6 +299,7 @@
  * \param fname_base filename base to record to
  * \param need_lock whether to lock the channel mutex
  * \param stream_action whether to record the input and/or output streams.  X_REC_IN | X_REC_OUT is most often used
+ * \param beep_id
  * Creates the file to record, if no format is specified it assumes WAV
  * It also sets channel variable __MONITORED=yes
  * \retval 0 on success
@@ -458,7 +459,7 @@
  * \param chan
  * \param need_lock
  * Stop the recording, close any open streams, mix in/out channels if required
- * \return Always 0
+ * \retval 0 Always
 */
 int AST_OPTIONAL_API_NAME(ast_monitor_stop)(struct ast_channel *chan, int need_lock)
 {
diff --git a/res/res_mwi_external.c b/res/res_mwi_external.c
index 9d56558..fac57ec 100644
--- a/res/res_mwi_external.c
+++ b/res/res_mwi_external.c
@@ -86,8 +86,6 @@
  * \internal
  * \brief Post an update event to the MWI counts.
  * \since 12.1.0
- *
- * \return Nothing
  */
 static void mwi_post_event(const struct ast_mwi_mailbox_object *mailbox)
 {
@@ -104,8 +102,6 @@
  * \internal
  * \brief Post a count clearing event to the MWI counts.
  * \since 12.1.0
- *
- * \return Nothing
  */
 static void mwi_observe_delete(const void *obj)
 {
@@ -254,8 +250,6 @@
  * \since 12.1.0
  *
  * \param mailbox Mailbox object to delete from sorcery.
- *
- * \return Nothing
  */
 static void mwi_mailbox_delete(struct ast_mwi_mailbox_object *mailbox)
 {
@@ -268,8 +262,6 @@
  * \since 12.1.0
  *
  * \param mailboxes Mailbox objects to delete from sorcery.
- *
- * \return Nothing
  */
 static void mwi_mailbox_delete_all(struct ao2_container *mailboxes)
 {
@@ -658,8 +650,6 @@
  *
  * \param cli_fd File descriptor for CLI output.
  * \param mailbox What to list.
- *
- * \return Nothing
  */
 static void mwi_cli_print_mailbox(int cli_fd, const struct ast_mwi_mailbox_object *mailbox)
 {
@@ -676,8 +666,6 @@
  *
  * \param cli_fd File descriptor for CLI output.
  * \param mailboxes What to list.
- *
- * \return Nothing
  */
 static void mwi_cli_list_mailboxes(int cli_fd, struct ao2_container *mailboxes)
 {
@@ -882,8 +870,6 @@
  * \internal
  * \brief Post initial MWI count events.
  * \since 12.1.0
- *
- * \return Nothing
  */
 static void mwi_initial_events(void)
 {
diff --git a/res/res_phoneprov.c b/res/res_phoneprov.c
index b0906c9..a050047 100644
--- a/res/res_phoneprov.c
+++ b/res/res_phoneprov.c
@@ -505,6 +505,7 @@
 
 /*! \brief Build a route structure and add it to the list of available http routes
 	\param pp_file File to link to the route
+	\param profile
 	\param user User to link to the route (NULL means static route)
 	\param uri URI of the route
 */
diff --git a/res/res_pjsip/pjsip_resolver.c b/res/res_pjsip/pjsip_resolver.c
index 3d03269..2babfe4 100644
--- a/res/res_pjsip/pjsip_resolver.c
+++ b/res/res_pjsip/pjsip_resolver.c
@@ -92,8 +92,6 @@
  * \brief Destroy resolution data
  *
  * \param data The resolution data to destroy
- *
- * \return Nothing
  */
 static void sip_resolve_destroy(void *data)
 {
@@ -185,7 +183,7 @@
  *
  * \param data The complete resolution
  *
- * \return Nothing
+ * \retval 0 Always
  */
 static int sip_resolve_invoke_user_callback(void *data)
 {
@@ -262,8 +260,6 @@
  * \brief Query set callback function, invoked when all queries have completed
  *
  * \param query_set The completed query set
- *
- * \return Nothing
  */
 static void sip_resolve_callback(const struct ast_dns_query_set *query_set)
 {
@@ -630,8 +626,6 @@
  * \param pool A memory pool to allocate things from
  * \param transport The type of transport to check
  * \param name A friendly name to print in the verbose message
- *
- * \return Nothing
  */
 static void sip_check_transport(pj_pool_t *pool, pjsip_transport_type_e transport, const char *name)
 {
diff --git a/res/res_pjsip_history.c b/res/res_pjsip_history.c
index ca86f24..de1063b 100644
--- a/res/res_pjsip_history.c
+++ b/res/res_pjsip_history.c
@@ -236,7 +236,7 @@
 	return !evaluate_equal(op, type, op_left, op_right);
 }
 
-/*
+/*!
  * \brief Operator callback for determining if one operand is less than another
  */
 static int evaluate_less_than(struct operator *op, enum aco_option_type type, void *op_left, struct expression_token *op_right)
@@ -285,7 +285,7 @@
 	return -1;
 }
 
-/*
+/*!
  * \brief Operator callback for determining if one operand is greater than another
  */
 static int evaluate_greater_than(struct operator *op, enum aco_option_type type, void *op_left, struct expression_token *op_right)
@@ -334,7 +334,7 @@
 	return -1;
 }
 
-/*
+/*!
  * \brief Operator callback for determining if one operand is less than or equal to another
  */
 static int evaluate_less_than_or_equal(struct operator *op, enum aco_option_type type, void *op_left, struct expression_token *op_right)
@@ -342,7 +342,7 @@
 	return !evaluate_greater_than(op, type, op_left, op_right);
 }
 
-/*
+/*!
  * \brief Operator callback for determining if one operand is greater than or equal to another
  */
 static int evaluate_greater_than_or_equal(struct operator *op, enum aco_option_type type, void *op_left, struct expression_token *op_right)
@@ -350,7 +350,7 @@
 	return !evaluate_less_than(op, type, op_left, op_right);
 }
 
-/*
+/*!
  * \brief Operator callback for determining logical NOT
  */
 static int evaluate_not(struct operator *op, enum aco_option_type type, void *operand)
@@ -368,7 +368,7 @@
 	return -1;
 }
 
-/*
+/*!
  * \brief Operator callback for determining logical AND
  */
 static int evaluate_and(struct operator *op, enum aco_option_type type, void *op_left, struct expression_token *op_right)
@@ -386,7 +386,7 @@
 	return -1;
 }
 
-/*
+/*!
  * \brief Operator callback for determining logical OR
  */
 static int evaluate_or(struct operator *op, enum aco_option_type type, void *op_left, struct expression_token *op_right)
@@ -404,7 +404,7 @@
 	return -1;
 }
 
-/*
+/*!
  * \brief Operator callback for regex 'like'
  */
 static int evaluate_like(struct operator *op, enum aco_option_type type, void *op_left, struct expression_token *op_right)
diff --git a/res/res_pjsip_mwi.c b/res/res_pjsip_mwi.c
index 650c402..653cd5a 100644
--- a/res/res_pjsip_mwi.c
+++ b/res/res_pjsip_mwi.c
@@ -679,8 +679,8 @@
  * \param container The ao2_container to search
  * \param endpoint The endpoint to find
  * \param mailbox The mailbox potentially subscribed
- * \param mwi_sub [out] May contain the located mwi_subscription
- * \param mwi_stasis [out] May contain the located mwi_stasis_subscription
+ * \param[out] mwi_sub May contain the located mwi_subscription
+ * \param[out] mwi_stasis May contain the located mwi_stasis_subscription
  *
  * \retval 1 if a subscription was located, 0 otherwise
  */
diff --git a/res/res_pjsip_notify.c b/res/res_pjsip_notify.c
index 9066b8c..3ae9f62 100644
--- a/res/res_pjsip_notify.c
+++ b/res/res_pjsip_notify.c
@@ -671,8 +671,8 @@
  * \internal
  * \brief Send a NOTIFY request to the endpoint.
  *
- * \detail Iterates over an endpoint's AORs sending a NOTIFY request
- *         with the appropriate payload information to each contact.
+ * \details Iterates over an endpoint's AORs sending a NOTIFY request
+ *          with the appropriate payload information to each contact.
  */
 static int notify_endpoint(void *obj)
 {
@@ -1072,7 +1072,7 @@
 };
 
 /*!
- * \interanl
+ * \internal
  * \brief Completes SIPNotify AMI command in Endpoint mode.
  */
 static void manager_notify_endpoint(struct mansession *s,
diff --git a/res/res_pjsip_session.c b/res/res_pjsip_session.c
index 7406d51..3f3de31 100644
--- a/res/res_pjsip_session.c
+++ b/res/res_pjsip_session.c
@@ -3722,9 +3722,9 @@
 	return SIP_GET_DEST_EXTEN_NOT_FOUND;
 }
 
-/*
- * /internal
- * /brief Process initial answer for an incoming invite
+/*!
+ * \internal
+ * \brief Process initial answer for an incoming invite
  *
  * This function should only be called during the setup, and handling of a
  * new incoming invite. Most, if not all of the time, this will be called
@@ -3772,10 +3772,10 @@
 	return res;
 }
 
-/*
- * /internal
- * /brief Create and initialize a pjsip invite session
-
+/*!
+ * \internal
+ * \brief Create and initialize a pjsip invite session
+ *
  * pjsip_inv_session adds, and maintains a reference to the dialog upon a successful
  * invite session creation until the session is destroyed. However, we'll wait to
  * remove the reference that was added for the dialog when it gets created since we're
@@ -3785,10 +3785,10 @@
  * created, and associated dialog locked and with two references (i.e. dialog's
  * reference count should be 2).
  *
- * \param endpoint A pointer to the endpoint
  * \param rdata The request that is starting the dialog
+ * \param endpoint A pointer to the endpoint
  *
- * \retval A pjsip invite session object
+ * \return A pjsip invite session object
  * \retval NULL on error
  */
 static pjsip_inv_session *pre_session_setup(pjsip_rx_data *rdata, const struct ast_sip_endpoint *endpoint)
diff --git a/res/res_rtp_asterisk.c b/res/res_rtp_asterisk.c
index 0f64a07..716f3a3 100644
--- a/res/res_rtp_asterisk.c
+++ b/res/res_rtp_asterisk.c
@@ -3462,8 +3462,6 @@
  * \brief Start the strictrtp learning mode.
  *
  * \param rtp RTP session description
- *
- * \return Nothing
  */
 static void rtp_learning_start(struct ast_rtp *rtp)
 {
@@ -3480,8 +3478,6 @@
 /*!
  * \internal
  * \brief Resets and ACL to empty state.
- *
- * \return Nothing
  */
 static void rtp_unload_acl(ast_rwlock_t *lock, struct ast_acl_list **acl)
 {
diff --git a/res/res_stasis.c b/res/res_stasis.c
index b74e135..ea1b7a0 100644
--- a/res/res_stasis.c
+++ b/res/res_stasis.c
@@ -1320,7 +1320,7 @@
 	ast_channel_unlock(chan);
 }
 
-/*! /brief Stasis dialplan application callback */
+/*! \brief Stasis dialplan application callback */
 int stasis_app_exec(struct ast_channel *chan, const char *app_name, int argc,
 		    char *argv[])
 {
@@ -2223,7 +2223,7 @@
 	return 0;
 }
 
-/* \brief Sanitization callback for channel snapshots */
+/*! \brief Sanitization callback for channel snapshots */
 static int channel_snapshot_sanitizer(const struct ast_channel_snapshot *snapshot)
 {
 	if (!snapshot || !(snapshot->tech_properties & AST_CHAN_TP_INTERNAL)) {
@@ -2232,7 +2232,7 @@
 	return 1;
 }
 
-/* \brief Sanitization callback for channels */
+/*! \brief Sanitization callback for channels */
 static int channel_sanitizer(const struct ast_channel *chan)
 {
 	if (!chan || !(ast_channel_tech(chan)->properties & AST_CHAN_TP_INTERNAL)) {
@@ -2241,7 +2241,7 @@
 	return 1;
 }
 
-/* \brief Sanitization callback for channel unique IDs */
+/*! \brief Sanitization callback for channel unique IDs */
 static int channel_id_sanitizer(const char *id)
 {
 	struct ast_channel_snapshot *snapshot;
@@ -2254,7 +2254,7 @@
 	return ret;
 }
 
-/* \brief Sanitization callbacks for communication to Stasis applications */
+/*! \brief Sanitization callbacks for communication to Stasis applications */
 struct stasis_message_sanitizer app_sanitizer = {
 	.channel_id = channel_id_sanitizer,
 	.channel_snapshot = channel_snapshot_sanitizer,
diff --git a/res/res_stir_shaken/certificate.h b/res/res_stir_shaken/certificate.h
index c95cba5..9f59afd 100644
--- a/res/res_stir_shaken/certificate.h
+++ b/res/res_stir_shaken/certificate.h
@@ -27,10 +27,10 @@
 /*!
  * \brief Get a STIR/SHAKEN certificate by caller ID number
  *
- * \param callier_id_number The caller ID number
+ * \param caller_id_number The caller ID number
  *
  * \retval NULL if not found
- * \retval The certificate on success
+ * \return The certificate on success
  */
 struct stir_shaken_certificate *stir_shaken_certificate_get_by_caller_id_number(const char *caller_id_number);
 
@@ -40,7 +40,7 @@
  * \param cert The certificate to get the public key URL from
  *
  * \retval NULL on failure
- * \retval The public key URL on success
+ * \return The public key URL on success
  */
 const char *stir_shaken_certificate_get_public_cert_url(struct stir_shaken_certificate *cert);
 
@@ -60,7 +60,7 @@
  * \param cert The certificate to get the private key from
  *
  * \retval NULL on failure
- * \retval The private key on success
+ * \return The private key on success
  */
 EVP_PKEY *stir_shaken_certificate_get_private_key(struct stir_shaken_certificate *cert);
 
@@ -94,14 +94,16 @@
 /*!
  * \brief Load time initialization for the stir/shaken 'certificate' configuration
  *
- * \retval 0 on success, -1 on error
+ * \retval 0 on success
+ * \retval -1 on error
  */
 int stir_shaken_certificate_load(void);
 
 /*!
  * \brief Unload time cleanup for the stir/shaken 'certificate' configuration
  *
- * \retval 0 on success, -1 on error
+ * \retval 0 on success
+ * \retval -1 on error
  */
 int stir_shaken_certificate_unload(void);
 
diff --git a/res/res_stir_shaken/curl.c b/res/res_stir_shaken/curl.c
index e765b5d..ad3adbc 100644
--- a/res/res_stir_shaken/curl.c
+++ b/res/res_stir_shaken/curl.c
@@ -81,6 +81,7 @@
 /*!
  * \brief Called when a CURL request completes
  *
+ * \param buffer, size, nitems
  * \param data The curl_cb_data structure to store expiration info
  */
 static size_t curl_header_callback(char *buffer, size_t size, size_t nitems, void *data)
@@ -123,7 +124,7 @@
  * \param data The CURL callback data
  *
  * \retval NULL on failure
- * \retval CURL instance on success
+ * \return CURL instance on success
  */
 static CURL *get_curl_instance(struct curl_cb_data *data)
 {
@@ -159,7 +160,7 @@
  * \param filename Function allocates memory and stores full filename (including path) here
  *
  * \retval -1 on failure
- * \retval file descriptor on success
+ * \return file descriptor on success
  */
 static int create_temp_file(const char *path, char **filename)
 {
diff --git a/res/res_stun_monitor.c b/res/res_stun_monitor.c
index 08d1d66..02cc85f 100644
--- a/res/res_stun_monitor.c
+++ b/res/res_stun_monitor.c
@@ -80,7 +80,7 @@
 	}
 }
 
-/* \brief called by scheduler to send STUN request */
+/*! \brief called by scheduler to send STUN request */
 static int stun_monitor_request(const void *blarg)
 {
 	int res;
@@ -202,8 +202,6 @@
  * \brief Stops the STUN monitor thread.
  *
  * \note do not hold the args->lock while calling this
- *
- * \return Nothing
  */
 static void stun_stop_monitor(void)
 {
@@ -226,8 +224,6 @@
  * \brief Starts the STUN monitor thread.
  *
  * \note The args->lock MUST be held when calling this function
- *
- * \return Nothing
  */
 static int stun_start_monitor(void)
 {
@@ -265,6 +261,7 @@
  * \brief Parse and setup the stunaddr parameter.
  *
  * \param value Configuration parameter variable value.
+ * \param reload
  *
  * \retval 0 on success.
  * \retval -1 on error.
diff --git a/res/res_xmpp.c b/res/res_xmpp.c
index f86828f..1c44aec 100644
--- a/res/res_xmpp.c
+++ b/res/res_xmpp.c
@@ -4124,7 +4124,7 @@
 
 }
 
-/*
+/*!
  * \brief Method to expose PubSub node list via CLI.
  * \param e pointer to ast_cli_entry structure
  * \param cmd
diff --git a/res/snmp/agent.h b/res/snmp/agent.h
index 21389d6..82f8289 100644
--- a/res/snmp/agent.h
+++ b/res/snmp/agent.h
@@ -17,15 +17,15 @@
 /*!
  * \internal
  * \brief Thread running the SNMP Agent or Subagent
- * \param Not used -- required by pthread_create
+ * \param arg -- not used
  * \return A pointer with return status -- not used
  *
  * This represent the main thread of the SNMP [sub]agent, and
  * will initialize SNMP and loop, processing requests until
  * termination is requested by resetting the flag in
- * \ref res_snmp_dontStop.
+ * \ref res_snmp_dont_stop.
  */
-void	*agent_thread(void *);
+void	*agent_thread(void *arg);
 
 /*!
  * \internal
diff --git a/res/stasis/app.h b/res/stasis/app.h
index a59f1dc..c6be69b 100644
--- a/res/stasis/app.h
+++ b/res/stasis/app.h
@@ -37,12 +37,12 @@
 struct stasis_app;
 
 enum stasis_app_subscription_model {
-	/*
+	/*!
 	 * \brief An application must manually subscribe to each
 	 * resource that it cares about. This is the default approach.
 	 */
 	STASIS_APP_SUBSCRIBE_MANUAL,
-	/*
+	/*!
 	 * \brief An application is automatically subscribed to all
 	 * resources in Asterisk, even if it does not control them.
 	 */

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

Gerrit-Project: asterisk
Gerrit-Branch: 16
Gerrit-Change-Id: I572e6019c422780dde5ce8448b6c85c77af6046d
Gerrit-Change-Number: 17512
Gerrit-PatchSet: 6
Gerrit-Owner: Alexander Traud <pabstraud at compuserve.com>
Gerrit-Reviewer: Benjamin Keith Ford <bford at digium.com>
Gerrit-Reviewer: Friendly Automation
Gerrit-Reviewer: George Joseph <gjoseph at digium.com>
Gerrit-Reviewer: Kevin Harwell <kharwell at digium.com>
Gerrit-MessageType: merged
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20211203/a192e6ef/attachment-0001.html>


More information about the asterisk-code-review mailing list