res: Fix for Doxygen.

These are the remaining issues found in /res. ASTERISK-29761 Change-Id: I572e6019c422780dde5ce8448b6c85c77af6046d
2025-09-04 20:04:50 +00:00 · 2021-11-19 10:11:08 +01:00
parent 3162f6dfdd
commit 14736ae6d4
32 changed files with 104 additions and 147 deletions
--- a/include/asterisk/calendar.h
+++ b/include/asterisk/calendar.h
@@ -152,9 +152,6 @@ int ast_calendar_register(struct ast_calendar_tech *tech);
 /*! \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);

--- a/include/asterisk/http_websocket.h
+++ b/include/asterisk/http_websocket.h
@@ -127,10 +127,10 @@ struct ast_websocket_protocol {
 };

 /*!
- * \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 @@ AST_OPTIONAL_API(int, ast_websocket_uri_cb, (struct ast_tcptls_session_instance
 /*!
 * \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 @@ AST_OPTIONAL_API(int, ast_websocket_add_protocol, (const char *name, ast_websock
 * \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 @@ AST_OPTIONAL_API(int, ast_websocket_remove_protocol, (const char *name, ast_webs
 /*!
 * \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 @@ AST_OPTIONAL_API(int, ast_websocket_server_add_protocol, (struct ast_websocket_s
 * \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 @@ AST_OPTIONAL_API(int, ast_websocket_server_add_protocol2, (struct ast_websocket_
 /*!
 * \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 @@ AST_OPTIONAL_API(int, ast_websocket_read, (struct ast_websocket *session, char *
 * \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 @@ AST_OPTIONAL_API(void, ast_websocket_unref, (struct ast_websocket *session), {re
 /*!
 * \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 @@ AST_OPTIONAL_API(int, ast_websocket_wait_for_input, (struct ast_websocket *sessi
 /*!
 * \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 @@ AST_OPTIONAL_API(int, ast_websocket_set_nonblock, (struct ast_websocket *session
 /*!
 * \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 @@ enum ast_websocket_result {
 /*!
 * \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 @@ AST_OPTIONAL_API(struct ast_websocket *, ast_websocket_client_create,
 * \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,
--- a/include/asterisk/phoneprov.h
+++ b/include/asterisk/phoneprov.h
@@ -95,7 +95,7 @@ void ast_phoneprov_provider_unregister(char *provider_name);
 /*!
 * \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.
 *
--- a/include/asterisk/res_hep.h
+++ b/include/asterisk/res_hep.h
@@ -87,9 +87,9 @@ struct hepv3_capture_info {
 * 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 @@ struct hepv3_capture_info *hepv3_create_capture_info(const void *payload, size_t
 * \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 @@ int hepv3_send_packet(struct hepv3_capture_info *capture_info);
 *
 * \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);

--- a/include/asterisk/res_mwi_external.h
+++ b/include/asterisk/res_mwi_external.h
@@ -47,7 +47,7 @@ struct ast_mwi_mailbox_object;
 *
 * \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 @@ unsigned int ast_mwi_mailbox_get_msgs_old(const struct ast_mwi_mailbox_object *m
 *
 * \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 @@ struct ast_mwi_mailbox_object *ast_mwi_mailbox_copy(const struct ast_mwi_mailbox
 *
 * \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 @@ void ast_mwi_mailbox_set_msgs_new(struct ast_mwi_mailbox_object *mailbox, unsign
 *
 * \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 @@ int ast_mwi_mailbox_delete_all(void);
 *
 * \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 @@ const struct ast_mwi_mailbox_object *ast_mwi_mailbox_get(const char *mailbox_id)
 *
 * \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 @@ struct ao2_container *ast_mwi_mailbox_get_by_regex(const char *regex);
 * \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.
--- a/include/asterisk/res_pjproject.h
+++ b/include/asterisk/res_pjproject.h
@@ -59,8 +59,6 @@ int ast_pjproject_get_buildopt(char *option, char *format_string, ...) __attribu
 * \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 @@ void ast_pjproject_log_intercept_begin(int fd);
 * \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 @@ void ast_pjproject_log_intercept_end(void);
 * \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 @@ void ast_pjproject_caching_pool_init(pj_caching_pool *cp,
 * \since 13.21.0
 *
 * \param cp Caching pool factory to destroy
- *
- * \return Nothing
 */
 void ast_pjproject_caching_pool_destroy(pj_caching_pool *cp);

--- a/include/asterisk/res_pjsip.h
+++ b/include/asterisk/res_pjsip.h
@@ -2405,9 +2405,9 @@ void ast_copy_pj_str(char *dest, const pj_str_t *src, size_t size);
 *
 * \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 @@ 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);
--- 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 @@ struct ast_sip_cli_context {
 	unsigned show_details_only_level_0 : 1;
 };

-/*
+/*!
 * \brief CLI Formatter Registry Entry
 */
 struct ast_sip_cli_formatter_entry {
--- 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_OPTIONAL_API_ATTR(void, format(printf, 1, 5), ast_statsd_log_string_va,
 * 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