progdocs: Fix for Doxygen, the hidden parts.

ASTERISK-29779

Change-Id: If338163488498f65fa7248b60e80299c0a928e4b

include/asterisk/calendar.h

@@ -91,7 +91,7 @@ struct ast_calendar_attendee {
 	AST_LIST_ENTRY(ast_calendar_attendee) next;
 };
 
-/* \brief Calendar events */
+/*! \brief Calendar events */
 struct ast_calendar_event {
 	AST_DECLARE_STRING_FIELDS(
 		AST_STRING_FIELD(summary);

include/asterisk/channel.h

@@ -1427,7 +1427,7 @@ void ast_change_name(struct ast_channel *chan, const char *newname);
  * This function will unlink the channel from the global channels container
  * if it is still there and also release the current reference to the channel.
  *
- * \retval NULL, convenient for clearing invalid pointers
+ * \retval NULL convenient for clearing invalid pointers
  * \note Absolutely _NO_ channel locks should be held before calling this function.
  *
  * \since 1.8
@@ -1738,7 +1738,9 @@ void ast_channel_softhangup_withcause_locked(struct ast_channel *chan, int cause
  * \brief Compare a offset with the settings of when to hang a channel up
  * \param chan channel on which to check for hangup
  * \param offset offset in seconds and microseconds from current time
- * \return 1, 0, or -1
+ * \retval 1
+ * \retval 0
+ * \retval -1
  * This function compares a offset from current time with the absolute time
  * out on a channel (when to hang up). If the absolute time out on a channel
  * is earlier than current time plus the offset, it returns 1, if the two
@@ -2952,7 +2954,7 @@ struct ast_channel_iterator;
  * This function is used to destroy a channel iterator that was retrieved by
  * using one of the channel_iterator_xxx_new() functions.
  *
- * \return NULL, for convenience to clear out the pointer to the iterator that
+ * \retval NULL for convenience to clear out the pointer to the iterator that
  * was just destroyed.
  *
  * \since 1.8
@@ -3029,7 +3031,7 @@ struct ast_channel_iterator *ast_channel_iterator_all_new(void);
  *
  * \retval the next channel that matches the parameters used when the iterator
  *         was created.
- * \retval NULL, if no more channels match the iterator parameters.
+ * \retval NULL if no more channels match the iterator parameters.
  *
  * \since 1.8
  */

include/asterisk/cli.h

@@ -371,7 +371,7 @@ char *ast_complete_channels(const char *line, const char *word, int pos, int sta
  */
 void ast_cli_print_timestr_fromseconds(int fd, int seconds, const char *prefix);
 
-/*
+/*!
  * \brief Allow a CLI command to be executed while Asterisk is shutting down.
  *
  * CLI commands by defeault are disabled when Asterisk is shutting down. This is

include/asterisk/config.h

@@ -1026,7 +1026,7 @@ enum config_hook_flags {
 	butt,
 };
 
-/*
+/*!
  * \brief Callback when configuration is updated
  *
  * \param cfg A copy of the configuration that is being changed.

include/asterisk/datastore.h

@@ -44,8 +44,6 @@ struct ast_datastore_info {
 	 * It allows a datastore to fix any pointers it saved to the owning channel
 	 * in case that the owning channel has changed.  Generally, this would happen
 	 * when the datastore is set to be inherited, and a masquerade occurs.
-	 *
-	 * \return nothing.
 	 */
 	void (*chan_fixup)(void *data, struct ast_channel *old_chan, struct ast_channel *new_chan);
 
@@ -58,8 +56,6 @@ struct ast_datastore_info {
 	 *
 	 * This is the same as the above callback, except it is called for the channel
 	 * being masqueraded into instead of the channel that is masquerading.
-	 *
-	 * \return nothing.
 	 */
 	void (*chan_breakdown)(void *data, struct ast_channel *old_chan, struct ast_channel *new_chan);
 };

include/asterisk/http_websocket.h

@@ -122,7 +122,7 @@ struct ast_websocket_protocol {
 	unsigned int version;
 	/*! \brief Callback called when a new session is attempted. Optional. */
 	ast_websocket_pre_callback session_attempted;
-	/* \brief Callback called when a new session is established. Mandatory. */
+	/*! \brief Callback called when a new session is established. Mandatory. */
 	ast_websocket_callback session_established;
 };
 

include/asterisk/logger.h

@@ -671,8 +671,7 @@ void __attribute__((format (printf, 6, 7))) __ast_trace(const char *file, int li
  *
  * \param level The trace level
  * \param indent_type One of the \ref ast_trace_indent_type values
- * \param (optional) A printf style format string
- * \param (optional) Arguments
+ * \param ... A printf style format string, optionally with arguments
  *
  */
 #define ast_trace_raw(level, indent_type, ...) \
@@ -685,8 +684,7 @@ void __attribute__((format (printf, 6, 7))) __ast_trace(const char *file, int li
  * \brief Print a basic trace message
  *
  * \param level The trace level
- * \param (optional) A printf style format string
- * \param (optional) Arguments
+ * \param ... A printf style format string, optionally with arguments
  *
  *  This will print the file, line and function at the current indent level
  */
@@ -732,8 +730,7 @@ unsigned long _ast_trace_dec_indent(void);
  * \brief Print a trace message with details when a scope is entered or existed.
  *
  * \param level The trace level
- * \param (optional) A printf style format string
- * \param (optional) Arguments
+ * \param ... A printf style format string, optionally with arguments
  *
  *  This will print the file, line and function plus details at the current indent level.
  * \note Like RAII_VAR, this macro must be called before any code in the scope.
@@ -775,8 +772,7 @@ unsigned long _ast_trace_dec_indent(void);
  * \brief Scope Enter
  *
  * \param level The trace level
- * \param (optional) A printf style format string
- * \param (optional) Arguments
+ * \param ... A printf style format string, optionally with arguments
  */
 #define SCOPE_ENTER(level, ...) \
 	int __scope_level = level; \
@@ -797,8 +793,7 @@ unsigned long _ast_trace_dec_indent(void);
 /*!
  * \brief Scope Exit
  *
- * \param (optional) A printf style format string
- * \param (optional) Arguments
+ * \param ... A printf style format string, optionally with arguments
  *
  * \details
  * This macro can be used at the exit points of a statement block since it just prints the message.
@@ -816,8 +811,7 @@ unsigned long _ast_trace_dec_indent(void);
  * \brief Scope Exit with expression
  *
  * \param __expr An expression to execute after printing the message
- * \param (optional) A printf style format string
- * \param (optional) Arguments
+ * \param ... A printf style format string, optionally with arguments
  *
  * \details
  * Handy for getting out of or continuing loops.
@@ -846,8 +840,7 @@ unsigned long _ast_trace_dec_indent(void);
 /*!
  * \brief Scope Exit with return
  *
- * \param (optional) A printf style format string
- * \param (optional) Arguments
+ * \param ... A printf style format string, optionally with arguments
  *
  * \details
  * This macro can be used at the exit points of a function when no value
@@ -867,8 +860,7 @@ unsigned long _ast_trace_dec_indent(void);
  * \brief Scope Exit with return value
  *
  * \param __return_value The return value
- * \param (optional) A printf style format string
- * \param (optional) Arguments
+ * \param ... A printf style format string, optionally with arguments
  *
  * \details
  * This macro can be used at the exit points of a function when a value

include/asterisk/netsock2.h

@@ -820,7 +820,6 @@ static inline int _ast_addressfamily_to_sockaddrsize(int af, const char *file, i
  *
  * \param[out] addr The address of the ast_sockaddr to store into
  * \param sa The sockaddr structure (sockaddr_in or sockaddr_in6) to convert
- * \return Nothing
  */
 #define ast_sockaddr_from_sockaddr(addr,sa)	ast_sockaddr_copy_sockaddr(addr, sa, ast_addressfamily_to_sockaddrsize(((const struct sockaddr*)(sa))->sa_family))
 

include/asterisk/pbx.h

@@ -1026,7 +1026,7 @@ int ast_context_add_ignorepat(const char *context, const char *ignorepat, const
 
 int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
 
-/*
+/*!
  * \brief Remove an ignorepat
  *
  * \param context context from which to remove the pattern

include/asterisk/res_pjsip.h

@@ -3481,8 +3481,6 @@ int ast_sip_call_codec_str_to_pref(struct ast_flags *pref, const char *pref_str,
  * \param data User data to know what to do when transport shuts down.
  *
  * \note The callback does not need to care that data is an ao2 object.
- *
- * \return Nothing
  */
 typedef void (*ast_transport_monitor_shutdown_cb)(void *data);
 

include/asterisk/sorcery.h

@@ -321,7 +321,7 @@ struct ast_sorcery_wizard {
 	/*! \brief Callback for closing a wizard */
 	void (*close)(void *data);
 
-	/* \brief Callback for whether or not the wizard believes the object is stale */
+	/*! \brief Callback for whether or not the wizard believes the object is stale */
 	int (*is_stale)(const struct ast_sorcery *sorcery, void *data, void *object);
 
 	/*! \brief Optional callback for forcing a reload to occur, even if wizard has determined no changes */

include/asterisk/stasis.h

@@ -1051,8 +1051,6 @@ typedef struct stasis_message *(*cache_aggregate_calc_fn)(struct stasis_cache_en
  * any remote entities publishing state for a device.  e.g., An aggregate
  * MWI message is the old/new MWI counts accumulated from the local and
  * any remote entities publishing to a mailbox.
- *
- * \return Nothing
  */
 typedef void (*cache_aggregate_publish_fn)(struct stasis_topic *topic, struct stasis_message *aggregate);
 

include/asterisk/stasis_app_impl.h

@@ -51,13 +51,10 @@ int stasis_app_exec(struct ast_channel *chan, const char *app_name, int argc,
 /*!
  * \brief Typedef for data destructor for stasis app commands
  *
- * \param data Data to destroy.
- *
- * \details
  * This is called during destruction of the command or if we fail to schedule
  * a command. It is passed a pointer to the user-defined data of the command.
  *
- * \return Nothing
+ * \param data Data to destroy.
  */
 typedef void (*command_data_destructor_fn)(void *data);
 

include/asterisk/stasis_app_mailbox.h

@@ -49,15 +49,15 @@ enum stasis_mailbox_result {
  *        be set to the JSON representation of the mailbox
  *
  * \return stasis mailbox result code indicating success or failure and cause
- * \return \c NULL on error.
+ * \retval NULL on error.
  */
 enum stasis_mailbox_result stasis_app_mailbox_to_json(const char *name, struct ast_json **json);
 
 /*!
- * brief Convert mailboxes to json array
+ * \brief Convert mailboxes to json array
  *
  * \return JSON representation of the mailboxes
- * \return \c NULL on error.
+ * \retval NULL on error.
  */
 struct ast_json *stasis_app_mailboxes_to_json(void);
 
@@ -70,8 +70,8 @@ struct ast_json *stasis_app_mailboxes_to_json(void);
  * \param old_messages count of old (read) messages in the mailbox
  * \param new_messages count of new (unread) messages in the mailbox
  *
- * \return 0 if successful
- * \return -1 on internal error.
+ * \retval 0 if successful
+ * \retval -1 on internal error.
  */
 int stasis_app_mailbox_update(
 	const char *name, int old_messages, int new_messages);

include/asterisk/tcptls.h

@@ -169,7 +169,7 @@ struct ast_tcptls_session_instance {
   */
 struct ast_tcptls_session_instance *ast_tcptls_client_start(struct ast_tcptls_session_instance *tcptls_session);
 
-/* \brief Creates a client connection's ast_tcptls_session_instance. */
+/*! \brief Creates a client connection's ast_tcptls_session_instance. */
 struct ast_tcptls_session_instance *ast_tcptls_client_create(struct ast_tcptls_session_args *desc);
 
 void *ast_tcptls_server_root(void *);

include/asterisk/test.h

@@ -172,24 +172,17 @@ struct ast_json *ast_test_suite_get_blob(struct ast_test_suite_message_payload *
 /*!
  * \brief Notifies the test suite of a change in application state
  *
- * \details
  * Raises a TestEvent manager event with a subtype of StateChange.  Additional parameters
  * The fmt parameter allows additional parameters to be added to the manager event using
  * printf style statement formatting.
  *
- * \param state		The state the application has changed to
- * \param fmt		The message with format parameters to add to the manager event
- *
- * \return Nothing
- */
-void __ast_test_suite_event_notify(const char *file, const char *func, int line, const char *state, const char *fmt, ...)
-	__attribute__((format(printf, 5, 6)));
-
-/*!
- * \ref __ast_test_suite_event_notify()
+ * \param s The state the application has changed to
+ * \param f The message with format parameters to add to the manager event
  */
 #define ast_test_suite_event_notify(s, f, ...) \
 	__ast_test_suite_event_notify(__FILE__, __PRETTY_FUNCTION__, __LINE__, (s), (f), ## __VA_ARGS__)
+void __ast_test_suite_event_notify(const char *file, const char *func, int line, const char *state, const char *fmt, ...)
+	__attribute__((format(printf, 5, 6)));
 
 #else
 
@@ -292,7 +285,7 @@ typedef int (ast_test_cleanup_cb_t)(struct ast_test_info *info, struct ast_test
 /*!
  * \brief unregisters a test with the test framework
  *
- * \param test callback function (required)
+ * \param cb callback function (required)
  *
  * \retval 0 success
  * \retval -1 failure
@@ -302,7 +295,7 @@ int ast_test_unregister(ast_test_cb_t *cb);
 /*!
  * \brief registers a test with the test framework
  *
- * \param test callback function (required)
+ * \param cb callback function (required)
  *
  * \retval 0 success
  * \retval -1 failure
@@ -349,8 +342,6 @@ int ast_test_register_cleanup(const char *category, ast_test_cleanup_cb_t *cb);
  *
  * \param test Unit test control structure.
  * \param fmt printf type format string.
- *
- * \return Nothing
  */
 void ast_test_debug(struct ast_test *test, const char *fmt, ...) __attribute__((format(printf, 2, 3)));
 
@@ -368,19 +359,16 @@ void ast_test_set_result(struct ast_test *test, enum ast_test_result_state state
 /*!
  * \brief update test's status during testing.
  *
- * \param test currently executing test
+ * \param t currently executing test
+ * \param f printf type format string
  *
  * \retval 0 success
  * \retval -1 failure
  */
+#define ast_test_status_update(t, f, ...) __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (t), (f), ## __VA_ARGS__)
 int __ast_test_status_update(const char *file, const char *func, int line, struct ast_test *test, const char *fmt, ...)
 	__attribute__((format(printf, 5, 6)));
 
-/*!
- * \ref __ast_test_status_update()
- */
-#define ast_test_status_update(t, f, ...) __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (t), (f), ## __VA_ARGS__)
-
 /*!
  * \brief Check a test condition, failing the test if it's not true.
  *