res: Fix for Doxygen.

These are the remaining issues found in /res.

ASTERISK-29761

Change-Id: I572e6019c422780dde5ce8448b6c85c77af6046d

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);
 

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,

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.
  *

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);
 

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.

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);
 

include/asterisk/res_pjsip.h

@@ -2481,9 +2481,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);
 

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 {

include/asterisk/res_prometheus.h

@@ -53,10 +53,9 @@
  */
 #define PROMETHEUS_MAX_VALUE_LENGTH 32
 
-/**
+/*!
  * \brief Prometheus general configuration
  *
- * \details
  * While the config file should generally provide the configuration
  * for this module, it is useful for testing purposes to allow the
  * configuration to be injected into the module. This struct is
@@ -86,7 +85,6 @@ struct prometheus_general_config {
 /*!
  * \brief A function table for a metrics provider
  *
- * \details
  * It's generally nice to separate out things that provide metrics
  * from the core of this module. For those that want to be notified
  * when things happen in the core module, they can provide an instance
@@ -126,7 +124,7 @@ enum prometheus_metric_type {
 	 * \brief A metric whose value always goes up
 	 */
 	PROMETHEUS_METRIC_COUNTER = 0,
-	/*
+	/*!
 	 * \brief A metric whose value can bounce around like a jackrabbit
 	 */
 	PROMETHEUS_METRIC_GAUGE,
@@ -165,7 +163,6 @@ struct prometheus_label {
 /*!
  * \brief An actual, honest to god, metric.
  *
- * \details
  * A bit of effort has gone into making this structure as efficient as we
  * possibly can. Given that a *lot* of metrics can theoretically be dumped out,
  * and that Asterisk attempts to be a "real-time" system, we want this process
@@ -223,21 +220,20 @@ struct prometheus_metric {
 	/*!
 	 * \brief The current value.
 	 *
-	 * \details
 	 * If \c get_metric_value is set, this value is ignored until the callback
 	 * happens
 	 */
 	char value[PROMETHEUS_MAX_VALUE_LENGTH];
-	/*
+	/*!
 	 * \brief Callback function to obtain the metric value
-	 * \details
+	 *
 	 * If updates need to happen when the metric is gathered, provide the
 	 * callback function. Otherwise, leave it \c NULL.
 	 */
 	void (* get_metric_value)(struct prometheus_metric *metric);
 	/*!
 	 * \brief A list of children metrics
-	 * \details
+	 *
 	 * Children metrics have the same name but different label.
 	 *
 	 * Registration of a metric will automatically nest the metrics; otherwise
@@ -254,15 +250,9 @@ struct prometheus_metric {
 	AST_LIST_ENTRY(prometheus_metric) entry;
 };
 
-/**
+/*!
  * \brief Convenience macro for initializing a metric on the stack
  *
- * \param mtype The metric type. See \c prometheus_metric_type
- * \param n Name of the metric
- * \param h Help text for the metric
- * \param cb Callback function. Optional; may be \c NULL
- *
- * \details
  * When initializing a metric on the stack, various fields have to be provided
  * to initialize the metric correctly. This macro can be used to simplify the
  * process.
@@ -283,6 +273,10 @@ struct prometheus_metric {
  *			metric_values_get_counter_value_cb);
  * \endcode
  *
+ * \param mtype The metric type. See \c prometheus_metric_type
+ * \param n Name of the metric
+ * \param h Help text for the metric
+ * \param cb Callback function. Optional; may be \c NULL
  */
 #define PROMETHEUS_METRIC_STATIC_INITIALIZATION(mtype, n, h, cb) { \
 	.type = (mtype), \
@@ -294,15 +288,9 @@ struct prometheus_metric {
 	.get_metric_value = (cb), \
 }
 
-/**
+/*!
  * \brief Convenience macro for setting a label / value in a metric
  *
- * \param metric The metric to set the label on
- * \param label Position of the label to set
- * \param n Name of the label
- * \param v Value of the label
- *
- * \details
  * When creating nested metrics, it's helpful to set their label after they have
  * been declared but before they have been registered. This macro acts as a
  * convenience function to set the labels properly on a declared metric.
@@ -317,6 +305,10 @@ struct prometheus_metric {
  *		test_gauge_child_two, 1, "key_two", "value_two");
  * \endcode
  *
+ * \param metric The metric to set the label on
+ * \param label Position of the label to set
+ * \param n Name of the label
+ * \param v Value of the label
  */
 #define PROMETHEUS_METRIC_SET_LABEL(metric, label, n, v) do { \
 	ast_assert((label) < PROMETHEUS_MAX_LABELS); \
@@ -362,11 +354,11 @@ struct prometheus_metric *prometheus_counter_create(const char *name,
 struct prometheus_metric *prometheus_gauge_create(const char *name,
 	const char *help);
 
-/**
+/*!
  * \brief Convert a metric (and its children) into Prometheus compatible text
  *
  * \param metric The metric to convert to a string
- * \param [out] output The \c ast_str string to populate with the metric(s)
+ * \param[out] output The \c ast_str string to populate with the metric(s)
  */
 void prometheus_metric_to_string(struct prometheus_metric *metric,
 	struct ast_str **output);
@@ -374,7 +366,6 @@ void prometheus_metric_to_string(struct prometheus_metric *metric,
 /*!
  * \brief Defines a callback that will be invoked when the HTTP route is called
  *
- * \details
  * This callback presents the second way of passing metrics to a Prometheus
  * server. For metrics that are generated often or whose value needs to be
  * stored, metrics can be created and registered. For metrics that can be
@@ -477,12 +468,11 @@ void prometheus_metrics_provider_register(const struct prometheus_metrics_provid
 /*!
  * \brief Retrieve the current configuration of the module
  *
+ * config is an AO2 ref counted object
+ *
  * \note
  * This should primarily be done for testing purposes.
  *
- * \details
- * config is an AO2 ref counted object
- *
  * \retval NULL on error
  * \retval config on success
  */
@@ -491,20 +481,17 @@ struct prometheus_general_config *prometheus_general_config_get(void);
 /*!
  * \brief Set the configuration for the module
  *
- * \note
- * This should primarily be done for testing purposes
- *
- * \details
  * This is not a ref-stealing function. The reference count to \c config
  * will be incremented as a result of calling this method.
  *
+ * \note
+ * This should primarily be done for testing purposes
  */
 void prometheus_general_config_set(struct prometheus_general_config *config);
 
 /*!
  * \brief Allocate a new configuration object
  *
- * \details
  * The returned object is an AO2 ref counted object
  *
  * \retval NULL on error

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