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: I780ed8e0e8acdbdd8f8b75fb7baf5ef657af7a3f

diff --git a/channels/chan_sip.c b/channels/chan_sip.c
index 13d5b1f4b9c6d44b85a012783423185fe3322dfa..07cef0d3a18df328d1253bfe3cf30478c4709ec3 100644 (file)
--- a/channels/chan_sip.c
+++ b/channels/chan_sip.c
@@ -865,7 +865,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,
@@ -875,10 +874,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 f04284e65923d2ed7a7f2337fd7c566b9fb4e524..236ace6e635b5a044e05cbbada027fa23a883edc 100644 (file)
--- 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 9834b91223a2711ce7c9b17b8e268960c220e72d..9c383e9496831fc7333ba67cfc19cefb803160f2 100644 (file)
--- 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 3fed0483e0b24e1534b3d698578f364d88b0c4dd..fab080c3e23a0985b5c1b1629c9edc153d3475d8 100644 (file)
--- 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 ba444bb71815f18520144d15f7e35a28a9e29f11..1f4ec9560f2d50ee1b0c85d65fbf6af662100f69 100644 (file)
--- 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 bb2cae85217a19b7952e0643794e8e0d883a6b17..d6e203ff0a93fac452a51888da2f5cf38471ceaf 100644 (file)
--- 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;
 
 #ifndef AST_IN_CORE
@@ -1551,15 +1552,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.
@@ -1659,7 +1661,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 490ae9ed3ee136285b6c7c50bc66e9de213fdcb4..af5e8d5ac8e9aa5b988915101404b537d79307b4 100644 (file)
--- 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 77a2bcaf8dc978586e1a4fd8d0c9f75ddcbb55db..ec281bd534595aab98d7580007254bda9076a103 100644 (file)
--- 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 150222406dabf3e6fdeecb1004235caf07d0346b..6f3a08064c1062bf5bc3d2d24fb9ec98d2475a9f 100644 (file)
--- a/include/asterisk/mwi.h
+++ b/include/asterisk/mwi.h
@@ -109,8 +109,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 937139fd824d5f9262d4f5b2829309d5ed06fce7..c1eaec1a199becc85c9da3f2701192ebaf3e805b 100644 (file)
--- 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 bc34b66ead732370d794c74f4af0b078422d7222..fab87957b036bb53dfefb6b30e41ec789cbaa793 100644 (file)
--- 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 bd945cf65d2ff932066637717e75db68d2d36b1f..ac2370dd48218949b81d69a321b91182436e3d27 100644 (file)
--- 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 65ac88921fa86998db662d0443c580f318b53c18..be3c52acb36d93bc5df1699729e8803540f68a12 100644 (file)
--- 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 f2a0a567bfb6f1b02388a423c3a260ee3bacc2a1..becfe46eb6ee0da8497375a2987a9dfb57ddafcf 100644 (file)
--- 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 f91b047816c3c5c91cac25a795618f3260e41bb0..f13ba554b2cafd6ae19fd715ebf9e2a93c625458 100644 (file)
--- 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 1eca28d6d35a74493b0848b3abf0926d5c97f0ef..0f3b22efe7d5619720d2f7a4d25bd4c7a70bd5cb 100644 (file)
--- 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 9e453a9669030d6974955d1fa0a6004b0de2fcde..704e1f739b34eb4d1da5af08f9388676943b5e85 100644 (file)
--- 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 aff690ee8cd1baa3ebf436677143ec8b3c8558c8..326357999dbddfa551c82ff32650a747bf1d288e 100644 (file)
--- 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 e39af203e0ef2393b6488886289309819ed5794a..4ecb6f80d9c7fd3af365bd17dfca93dfc5367c8d 100644 (file)
--- a/main/mwi.c
+++ b/main/mwi.c
@@ -25,14 +25,16 @@
 #include "asterisk/mwi.h"
 #include "asterisk/stasis_channels.h"
 
-/*
- * @{ \brief Define \ref stasis topic objects
+/*!
+ * \brief Define \ref stasis topic objects
+ * @{
  */
 static struct stasis_topic *mwi_topic_all;
 static struct stasis_cache *mwi_state_cache;
 static struct stasis_caching_topic *mwi_topic_cached;
 static struct stasis_topic_pool *mwi_topic_pool;
-/* @} */
+
+/*! @} */
 
 /*! \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)
 {