progdocs: Fix grouping for latest Doxygen.

Since Doxygen 1.8.16, a special comment block is required. Otherwise (pure C comment), the group command is ignored. Additionally, several unbalanced group commands were fixed. ASTERISK-29732 Change-Id: I4687857b9d56e6f44fd440b73af156691660202e
2025-10-12 15:45:18 +00:00 · 2021-11-12 17:05:05 +01:00
parent bcb7aee723
commit 751bbf4b97
19 changed files with 92 additions and 64 deletions
--- a/include/asterisk/adsi.h
+++ b/include/asterisk/adsi.h
@@ -26,7 +26,7 @@
 #include "asterisk/callerid.h"

 /*! \name ADSI parameters */
-/*@{ */
+/*! @{ */

 /* ADSI Message types */
 #define ADSI_MSG_DISPLAY	132
@@ -122,7 +122,7 @@

 #define AST_ADSI_VERSION 1

-/*@} */
+/*! @} */

 int ast_adsi_begin_download(struct ast_channel *chan, char *service, unsigned char *fdn, unsigned char *sec, int version);

--- a/include/asterisk/app.h
+++ b/include/asterisk/app.h
@@ -1510,7 +1510,6 @@ struct stasis_topic *ast_queue_topic_all(void);
 * \since 12
 */
 struct stasis_topic *ast_queue_topic(const char *queuename);
-/*! @} */

 /*!
 * \brief Initialize the application core
--- a/include/asterisk/astmm.h
+++ b/include/asterisk/astmm.h
@@ -108,9 +108,7 @@ int __ast_repl_vasprintf(char **strp, const char *format, va_list ap, const char
 */
 #define ASTMM_IGNORE   2

-/*!
- * }@
- */
+/*! @} */

 #if !defined(ASTMM_LIBC)
 /* BLOCK libc allocators by default. */
--- a/include/asterisk/astobj2.h
+++ b/include/asterisk/astobj2.h
@@ -1281,8 +1281,9 @@ typedef int (ao2_sort_fn)(const void *obj_left, const void *obj_right, int flags

 /*! \name Object Containers
 * Here start declarations of containers.
+ *
+ * @{
 */
-/*@{ */
 struct ao2_container;

 /*!
@@ -1517,15 +1518,16 @@ int ao2_container_register(const char *name, struct ao2_container *self, ao2_prn
 */
 void ao2_container_unregister(const char *name);

-/*@} */
+/*! @} */

 /*! \name Object Management
 * Here we have functions to manage objects.
 *
 * We can use the functions below on any kind of
 * object defined by the user.
+ *
+ * @{
 */
-/*@{ */

 /*!
 * \brief Add an object to a container.
@@ -1625,7 +1627,7 @@ int __ao2_link(struct ao2_container *c, void *obj_new, int flags,
 void *__ao2_unlink(struct ao2_container *c, void *obj, int flags,
 	const char *tag, const char *file, int line, const char *func);

-/*@} */
+/*! @} */


 /*! \brief
--- a/include/asterisk/causes.h
+++ b/include/asterisk/causes.h
@@ -92,8 +92,9 @@ For more information:
 /*! \name Causes for disconnection (from Q.850/Q.931)
 *  These are the internal cause codes used in Asterisk.
 *  \ref AstCauses
+ *
+ * @{
 */
-/*@{ */
 #define AST_CAUSE_UNALLOCATED                    1
 #define AST_CAUSE_NO_ROUTE_TRANSIT_NET           2
 #define AST_CAUSE_NO_ROUTE_DESTINATION           3
@@ -153,6 +154,7 @@ For more information:
 #define AST_CAUSE_UNREGISTERED  AST_CAUSE_SUBSCRIBER_ABSENT
 #define AST_CAUSE_NOTDEFINED    0
 #define AST_CAUSE_NOSUCHDRIVER  AST_CAUSE_CHAN_NOT_IMPLEMENTED
-/*@} */
+
+/*! @} */

 #endif /* _ASTERISK_CAUSES_H */
--- a/include/asterisk/manager.h
+++ b/include/asterisk/manager.h
@@ -59,15 +59,19 @@
 #define DEFAULT_MANAGER_TLS_PORT 5039	/* Default port for Asterisk management via TCP */

 /*! \name Constant return values
- *\note Currently, returning anything other than zero causes the session to terminate.
+ * \note Currently, returning anything other than zero causes the session to terminate.
+ *
+ * @{
 */
-/*@{ */
 #define	AMI_SUCCESS	(0)
 #define	AMI_DESTROY	(-1)
-/*@} */

-/*! \name Manager event classes */
-/*@{ */
+/*! @} */
+
+/*! \name Manager event classes
+ *
+ * @{
+ */
 #define EVENT_FLAG_SYSTEM           (1 << 0) /* System events such as module load/unload */
 #define EVENT_FLAG_CALL             (1 << 1) /* Call event, such as state change, etc */
 #define EVENT_FLAG_LOG              (1 << 2) /* Log events */
@@ -89,7 +93,8 @@
 #define EVENT_FLAG_SECURITY         (1 << 18) /* Security Message as AMI Event */
 /*XXX Why shifted by 30? XXX */
 #define EVENT_FLAG_MESSAGE          (1 << 30) /* MESSAGE events. */
-/*@} */
+
+/*! @} */

 /*! \brief Export manager structures */
 #define AST_MAX_MANHEADERS 128
--- a/include/asterisk/mwi.h
+++ b/include/asterisk/mwi.h
@@ -446,8 +446,8 @@ int ast_publish_mwi_state_full(
 */
 int ast_delete_mwi_state_full(const char *mailbox, const char *context, struct ast_eid *eid);

-/*! \addtogroup StasisTopicsAndMessages
- * @{
+/*!
+ * \addtogroup StasisTopicsAndMessages
 */

 /*!
--- a/include/asterisk/netsock2.h
+++ b/include/asterisk/netsock2.h
@@ -752,8 +752,9 @@ int ast_set_qos(int sockfd, int tos, int cos, const char *desc);
 * These are backward compatibility functions that may be used by subsystems
 * that have not yet been converted to IPv6. They will be removed when all
 * subsystems are IPv6-ready.
+ *
+ * @{
 */
-/*@{*/

 /*!
 * \since 1.8
@@ -823,7 +824,7 @@ static inline int _ast_addressfamily_to_sockaddrsize(int af, const char *file, i
 */
 #define ast_sockaddr_from_sockaddr(addr,sa)	ast_sockaddr_copy_sockaddr(addr, sa, ast_addressfamily_to_sockaddrsize(((const struct sockaddr*)(sa))->sa_family))

-/*@}*/
+/*! @} */

 #if defined(__cplusplus) || defined(c_plusplus)
 }
--- a/include/asterisk/pbx.h
+++ b/include/asterisk/pbx.h
@@ -1401,9 +1401,9 @@ void pbx_substitute_variables_helper(struct ast_channel *c, const char *cp1, cha
 void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count);
 void pbx_substitute_variables_helper_full(struct ast_channel *c, struct varshead *headp, const char *cp1, char *cp2, int cp2_size, size_t *used);
 /*! @} */
-/*! @} */

-/*! @name Substitution routines, using dynamic string buffers */
+/*! @name Substitution routines, using dynamic string buffers
+ * @{ */

 /*!
 * \param buf Result will be placed in this buffer.
--- a/include/asterisk/rtp_engine.h
+++ b/include/asterisk/rtp_engine.h
@@ -2723,6 +2723,8 @@ struct stasis_message_type *ast_rtp_rtcp_sent_type(void);
 */
 struct stasis_message_type *ast_rtp_rtcp_received_type(void);

+/*! @} */
+
 #ifdef TEST_FRAMEWORK
 /*!
 * \brief Get the maximum size of the receive buffer
@@ -2898,8 +2900,6 @@ uintmax_t ast_debug_category_ice_id(void);
 #define ast_debug_ice(sublevel, ...) \
 	ast_debug_category(sublevel, AST_DEBUG_CATEGORY_ICE, __VA_ARGS__)

-/* @} */
-
 #if defined(__cplusplus) || defined(c_plusplus)
 }
 #endif
--- a/include/asterisk/smoother.h
+++ b/include/asterisk/smoother.h
@@ -36,8 +36,9 @@ extern "C" {
 #define AST_SMOOTHER_FLAG_FORCED	(1 << 2)

 /*! \name AST_Smoother
-*/
-/*@{ */
+ *
+ * @{
+ */
 /*! \page ast_smooth The AST Frame Smoother
 The ast_smoother interface was designed specifically
 to take frames of variant sizes and produce frames of a single expected
@@ -81,7 +82,8 @@ struct ast_frame *ast_smoother_read(struct ast_smoother *s);
 #define ast_smoother_feed_be(s,f) __ast_smoother_feed(s, f, 0)
 #define ast_smoother_feed_le(s,f) __ast_smoother_feed(s, f, 1)
 #endif
-/*@} Doxygen marker */
+
+/*! @} */

 #if defined(__cplusplus) || defined(c_plusplus)
 }
--- a/include/asterisk/stasis_app_mailbox.h
+++ b/include/asterisk/stasis_app_mailbox.h
@@ -31,8 +31,6 @@
 #include "asterisk/app.h"
 #include "asterisk/stasis_app.h"

-/*! @{ */
-
 /*! Stasis mailbox operation result codes */
 enum stasis_mailbox_result {
 	/*! Mailbox operation completed successfully */
--- a/include/asterisk/term.h
+++ b/include/asterisk/term.h
@@ -30,8 +30,9 @@ extern "C" {
 #define ESC 0x1b

 /*! \name Terminal Attributes
-*/
-/*@{ */
+ *
+ * @{
+ */
 #define ATTR_RESET	0
 #define ATTR_BRIGHT	1
 #define ATTR_DIM	2
@@ -39,11 +40,13 @@ extern "C" {
 #define ATTR_BLINK	5
 #define ATTR_REVER	7
 #define ATTR_HIDDEN	8
-/*@} */
+
+/*! @} */

 /*! \name Terminal Colors
-*/
-/*@{ */
+ *
+ * @{
+ */
 #define COLOR_BLACK     30
 #define COLOR_GRAY      (30 | 128)
 #define COLOR_RED       31
@@ -60,7 +63,8 @@ extern "C" {
 #define COLOR_BRCYAN    (36 | 128)
 #define COLOR_WHITE     37
 #define COLOR_BRWHITE   (37 | 128)
-/*@} */
+
+/*! @} */

 /*! \brief Shortcut macros for coloring a set of text
 */
--- a/include/asterisk/transcap.h
+++ b/include/asterisk/transcap.h
@@ -29,8 +29,9 @@
 */

 /*! \name AstTranscode General Asterisk channel transcoding definitions.
-*/
-/*@{ */
+ *
+ * @{
+ */
 #define AST_TRANS_CAP_SPEECH				0x0
 #define AST_TRANS_CAP_DIGITAL				0x08
 #define AST_TRANS_CAP_RESTRICTED_DIGITAL		0x09
@@ -38,7 +39,8 @@
 #define AST_TRANS_CAP_7K_AUDIO				0x11	/* Depriciated ITU Q.931 (05/1998)*/
 #define AST_TRANS_CAP_DIGITAL_W_TONES			0x11
 #define AST_TRANS_CAP_VIDEO				0x18
-/*@} */
+
+/*! @} */

 #define IS_DIGITAL(cap)\
 	(cap) & AST_TRANS_CAP_DIGITAL ? 1 : 0
--- a/include/jitterbuf.h
+++ b/include/jitterbuf.h
@@ -27,8 +27,9 @@
 extern "C" {
 #endif

-/*! \name configuration constants */
-/*@{ */
+/*! \name configuration constants
+ * @{
+ */
 	/*! Number of historical timestamps to use in calculating jitter and drift */
 #define JB_HISTORY_SZ		500
 	/*! what percentage of timestamps should we drop from the history when we examine it;
@@ -42,7 +43,8 @@ extern "C" {
 #define JB_TARGET_EXTRA 40
 	/*! ms between growing and shrinking; may not be honored if jitterbuffer runs out of space */
 #define JB_ADJUST_DELAY 40
-/*@} */
+
+/*! @} */

 enum jb_return_code {
 	/* return codes */