From affe7ee8799e0d620648d5bfc1edf4e801632b81 Mon Sep 17 00:00:00 2001
From: Alexander Traud <pabstraud@compuserve.com>
Date: Fri, 12 Nov 2021 17:05:05 +0100
Subject: [PATCH] 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
---
 channels/chan_sip.c                   |  5 +++--
 channels/sip/include/sip.h            | 26 ++++++++++++++++----------
 include/asterisk/adsi.h               |  4 ++--
 include/asterisk/app.h                |  1 -
 include/asterisk/astmm.h              |  4 +---
 include/asterisk/astobj2.h            | 10 ++++++----
 include/asterisk/causes.h             |  6 ++++--
 include/asterisk/manager.h            | 17 +++++++++++------
 include/asterisk/mwi.h                |  4 ++--
 include/asterisk/netsock2.h           |  5 +++--
 include/asterisk/pbx.h                |  4 ++--
 include/asterisk/rtp_engine.h         |  4 ++--
 include/asterisk/smoother.h           |  8 +++++---
 include/asterisk/stasis_app_mailbox.h |  2 --
 include/asterisk/term.h               | 16 ++++++++++------
 include/asterisk/transcap.h           |  8 +++++---
 include/jitterbuf.h                   |  8 +++++---
 main/app.c                            |  8 +++++---
 main/mwi.c                            | 16 ++++++++++------
 19 files changed, 92 insertions(+), 64 deletions(-)

diff --git a/channels/chan_sip.c b/channels/chan_sip.c
index 3e310e133e..e19e19db08 100644
--- a/channels/chan_sip.c
+++ b/channels/chan_sip.c
@@ -867,7 +867,6 @@ static int global_store_sip_cause;    /*!< Whether the MASTER_CHANNEL(HASH(SIP_C
 
 static int global_dynamic_exclude_static = 0; /*!< Exclude static peers from contact registrations */
 static unsigned char global_refer_addheaders; /*!< Add extra headers to outgoing REFER */
-/*@}*/
 
 /*!
  * We use libxml2 in order to parse XML that may appear in the body of a SIP message. Currently,
@@ -877,10 +876,12 @@ static unsigned char global_refer_addheaders; /*!< Add extra headers to outgoing
  */
 static int can_parse_xml;
 
-/*! \name Object counters @{
+/*! \name Object counters
  *
  * \bug These counters are not handled in a thread-safe way ast_atomic_fetchadd_int()
  * should be used to modify these values.
+ *
+ * @{
  */
 static int speerobjs = 0;     /*!< Static peers */
 static int rpeerobjs = 0;     /*!< Realtime peers */
diff --git a/channels/sip/include/sip.h b/channels/sip/include/sip.h
index bcc1cf81d8..1396d81d2e 100644
--- a/channels/sip/include/sip.h
+++ b/channels/sip/include/sip.h
@@ -185,8 +185,9 @@
    These are default values in the source. There are other recommended values in the
    sip.conf.sample for new installations. These may differ to keep backwards compatibility,
    yet encouraging new behaviour on new installations
+
+   @{
  */
-/*@{*/
 #define DEFAULT_CONTEXT        "default"  /*!< The default context for [general] section as well as devices */
 #define DEFAULT_RECORD_FEATURE   "automon"  /*!< The default feature specified for use with INFO */
 #define DEFAULT_MOHINTERPRET   "default"  /*!< The default music class */
@@ -235,7 +236,8 @@
 #define DEFAULT_ENGINE     "asterisk"      /*!< Default RTP engine to use for sessions */
 #define DEFAULT_STORE_SIP_CAUSE FALSE      /*!< Don't store HASH(SIP_CAUSE,<channel name>) for channels by default */
 #endif
-/*@}*/
+
+/*! @} */
 
 /*! \name SIPflags
 	Various flags for the flags field in the pvt structure
@@ -245,8 +247,8 @@
 	G: Global flag
 	When flags are used by multiple structures, it is important that
 	they have a common layout so it is easy to copy them.
-*/
-/*@{*/
+   @{
+ */
 #define SIP_OUTGOING        (1 << 0) /*!< D: Direction of the last transaction in this dialog */
 #define SIP_OFFER_CC        (1 << 1) /*!< D: Offer CC on subsequent responses */
 #define SIP_RINGING         (1 << 2) /*!< D: Have sent 180 ringing */
@@ -307,11 +309,13 @@
 	(SIP_PROMISCREDIR | SIP_TRUSTRPID | SIP_SENDRPID | SIP_DTMF | SIP_REINVITE | \
 	 SIP_PROG_INBAND | SIP_USECLIENTCODE | SIP_NAT_FORCE_RPORT | SIP_G726_NONSTANDARD | \
 	 SIP_USEREQPHONE | SIP_INSECURE | SIP_USEPATH)
-/*@}*/
+
+/*! @} */
 
 /*! \name SIPflags2
-	a second page of flags (for flags[1] */
-/*@{*/
+	a second page of flags (for flags[1]
+   @{
+ */
 /* realtime flags */
 #define SIP_PAGE2_RTCACHEFRIENDS            (1 <<  0)   /*!< GP: Should we keep RT objects in memory for extended time? */
 #define SIP_PAGE2_RTAUTOCLEAR               (1 <<  1)   /*!< GP: Should we clean memory from peers after expiry? */
@@ -393,7 +397,7 @@
 
 #define CHECK_AUTH_BUF_INITLEN   256
 
-/*@}*/
+/*! @} */
 
 /*----------------------------------------------------------*/
 /*----                    ENUMS                         ----*/
@@ -731,8 +735,8 @@ struct __show_chan_arg {
 /*! \name GlobalSettings
 	Global settings apply to the channel (often settings you can change in the general section
 	of sip.conf
-*/
-/*@{*/
+   @{
+ */
 /*! \brief a place to store all global settings for the sip channel driver
 
 	These are settings that will be possibly to apply on a group level later on.
@@ -784,6 +788,8 @@ struct sip_settings {
 	int websocket_enabled;       /*!< Are websockets enabled? */
 };
 
+/*! @} */
+
 struct ast_websocket;
 
 /*! \brief The SIP socket definition */
diff --git a/include/asterisk/adsi.h b/include/asterisk/adsi.h
index 9834b91223..9c383e9496 100644
--- 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);
 
diff --git a/include/asterisk/app.h b/include/asterisk/app.h
index 3fed0483e0..fab080c3e2 100644
--- 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
diff --git a/include/asterisk/astmm.h b/include/asterisk/astmm.h
index ba444bb718..1f4ec9560f 100644
--- 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. */
diff --git a/include/asterisk/astobj2.h b/include/asterisk/astobj2.h
index c32b7439b4..45ae509d7b 100644
--- 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
diff --git a/include/asterisk/causes.h b/include/asterisk/causes.h
index 490ae9ed3e..af5e8d5ac8 100644
--- 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 */
diff --git a/include/asterisk/manager.h b/include/asterisk/manager.h
index 4fbb3d8679..b9291da91e 100644
--- 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
diff --git a/include/asterisk/mwi.h b/include/asterisk/mwi.h
index 3ce2b0647d..cb149631b2 100644
--- 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
  */
 
 /*!
diff --git a/include/asterisk/netsock2.h b/include/asterisk/netsock2.h
index 937139fd82..c1eaec1a19 100644
--- 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)
 }
diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h
index bc34b66ead..fab87957b0 100644
--- 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.
diff --git a/include/asterisk/rtp_engine.h b/include/asterisk/rtp_engine.h
index bd945cf65d..ac2370dd48 100644
--- 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
diff --git a/include/asterisk/smoother.h b/include/asterisk/smoother.h
index 65ac88921f..be3c52acb3 100644
--- 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)
 }
diff --git a/include/asterisk/stasis_app_mailbox.h b/include/asterisk/stasis_app_mailbox.h
index f2a0a567bf..becfe46eb6 100644
--- 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 */
diff --git a/include/asterisk/term.h b/include/asterisk/term.h
index f91b047816..f13ba554b2 100644
--- 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
  */
diff --git a/include/asterisk/transcap.h b/include/asterisk/transcap.h
index 1eca28d6d3..0f3b22efe7 100644
--- 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
diff --git a/include/jitterbuf.h b/include/jitterbuf.h
index 9e453a9669..704e1f739b 100644
--- 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 */
diff --git a/main/app.c b/main/app.c
index aff690ee8c..326357999d 100644
--- a/main/app.c
+++ b/main/app.c
@@ -83,12 +83,14 @@ static AST_LIST_HEAD_STATIC(zombies, zombie);
 #ifdef HAVE_CAP
 static cap_t child_cap;
 #endif
-/*
- * @{ \brief Define \ref stasis topic objects
+/*!
+ * \brief Define \ref stasis topic objects
+ * @{
  */
 static struct stasis_topic *queue_topic_all;
 static struct stasis_topic_pool *queue_topic_pool;
-/* @} */
+
+/*! @} */
 
 static void *shaun_of_the_dead(void *data)
 {
diff --git a/main/mwi.c b/main/mwi.c
index e81766cbc2..2d7ede3977 100644
--- a/main/mwi.c
+++ b/main/mwi.c
@@ -26,13 +26,15 @@
 #include "asterisk/mwi.h"
 #include "asterisk/stasis_channels.h"
 
-/*
- * @{ \brief Define \ref stasis topic objects
+/*!
+ * \brief Define \ref stasis topic objects
+ * @{
  */
 static struct stasis_state_manager *mwi_state_manager;
 static struct stasis_cache *mwi_state_cache;
 static struct stasis_caching_topic *mwi_topic_cached;
-/* @} */
+
+/*! @} */
 
 /*! \brief Convert a MWI \ref stasis_message to a \ref ast_event */
 static struct ast_event *mwi_to_event(struct stasis_message *message)
@@ -66,13 +68,15 @@ static struct ast_event *mwi_to_event(struct stasis_message *message)
 	return event;
 }
 
-/*
- * @{ \brief Define \ref stasis message types for MWI
+/*!
+ * \brief Define \ref stasis message types for MWI
+ * @{
  */
 STASIS_MESSAGE_TYPE_DEFN(ast_mwi_state_type,
 	.to_event = mwi_to_event, );
 STASIS_MESSAGE_TYPE_DEFN(ast_mwi_vm_app_type);
-/* @} */
+
+/*! @} */
 
 static void mwi_state_dtor(void *obj)
 {