[Asterisk-code-review] progdocs: Fix grouping for latest Doxygen. (asterisk[master])

Kevin Harwell asteriskteam at digium.com
Thu Dec 2 10:26:10 CST 2021 

Kevin Harwell has submitted this change. ( https://gerrit.asterisk.org/c/asterisk/+/17334 )

Change subject: progdocs: Fix grouping for latest Doxygen.
......................................................................

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
---
M channels/chan_sip.c
M channels/sip/include/sip.h
M include/asterisk/adsi.h
M include/asterisk/app.h
M include/asterisk/astmm.h
M include/asterisk/astobj2.h
M include/asterisk/causes.h
M include/asterisk/manager.h
M include/asterisk/mwi.h
M include/asterisk/netsock2.h
M include/asterisk/pbx.h
M include/asterisk/rtp_engine.h
M include/asterisk/smoother.h
M include/asterisk/stasis_app_mailbox.h
M include/asterisk/term.h
M include/asterisk/transcap.h
M include/jitterbuf.h
M main/app.c
M main/mwi.c
19 files changed, 92 insertions(+), 64 deletions(-)

Approvals:
  Kevin Harwell: Looks good to me, approved; Approved for Submit
  Benjamin Keith Ford: Looks good to me, but someone else must approve



diff --git a/channels/chan_sip.c b/channels/chan_sip.c
index 3e310e1..e19e19d 100644
--- a/channels/chan_sip.c
+++ b/channels/chan_sip.c
@@ -867,7 +867,6 @@
 
 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 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 bcc1cf8..1396d81 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 @@
 /*! \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 @@
 	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 9834b91..9c383e9 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 3fed048..fab080c3 100644
--- a/include/asterisk/app.h
+++ b/include/asterisk/app.h
@@ -1510,7 +1510,6 @@
  * \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 ba444bb..1f4ec95 100644
--- a/include/asterisk/astmm.h
+++ b/include/asterisk/astmm.h
@@ -108,9 +108,7 @@
  */
 #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 c32b743..45ae509 100644
--- a/include/asterisk/astobj2.h
+++ b/include/asterisk/astobj2.h
@@ -1281,8 +1281,9 @@
 
 /*! \name Object Containers
  * Here start declarations of containers.
+ *
+ * @{
  */
-/*@{ */
 struct ao2_container;
 
 /*!
@@ -1517,15 +1518,16 @@
  */
 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 @@
 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 490ae9e..af5e8d5 100644
--- a/include/asterisk/causes.h
+++ b/include/asterisk/causes.h
@@ -92,8 +92,9 @@
 /*! \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 @@
 #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 4fbb3d8..b9291da 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 3ce2b06..cb14963 100644
--- a/include/asterisk/mwi.h
+++ b/include/asterisk/mwi.h
@@ -446,8 +446,8 @@
  */
 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 937139f..c1eaec1 100644
--- a/include/asterisk/netsock2.h
+++ b/include/asterisk/netsock2.h
@@ -752,8 +752,9 @@
  * 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 @@
  */
 #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 bc34b66..fab8795 100644
--- a/include/asterisk/pbx.h
+++ b/include/asterisk/pbx.h
@@ -1401,9 +1401,9 @@
 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 bd945cf..ac2370d 100644
--- a/include/asterisk/rtp_engine.h
+++ b/include/asterisk/rtp_engine.h
@@ -2723,6 +2723,8 @@
  */
 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 @@
 #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 65ac889..be3c52a 100644
--- a/include/asterisk/smoother.h
+++ b/include/asterisk/smoother.h
@@ -36,8 +36,9 @@
 #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 @@
 #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 f2a0a56..becfe46 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 f91b047..f13ba55 100644
--- a/include/asterisk/term.h
+++ b/include/asterisk/term.h
@@ -30,8 +30,9 @@
 #define ESC 0x1b
 
 /*! \name Terminal Attributes
-*/
-/*@{ */
+ *
+ * @{
+ */
 #define ATTR_RESET	0
 #define ATTR_BRIGHT	1
 #define ATTR_DIM	2
@@ -39,11 +40,13 @@
 #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 @@
 #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 1eca28d..0f3b22e 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 9e453a9..704e1f7 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 @@
 #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 aff690e..3263579 100644
--- a/main/app.c
+++ b/main/app.c
@@ -83,12 +83,14 @@
 #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 e81766c..2d7ede3 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 @@
 	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)
 {

-- 
To view, visit https://gerrit.asterisk.org/c/asterisk/+/17334
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings

Gerrit-Project: asterisk
Gerrit-Branch: master
Gerrit-Change-Id: I4687857b9d56e6f44fd440b73af156691660202e
Gerrit-Change-Number: 17334
Gerrit-PatchSet: 4
Gerrit-Owner: Alexander Traud <pabstraud at compuserve.com>
Gerrit-Reviewer: Benjamin Keith Ford <bford at digium.com>
Gerrit-Reviewer: Friendly Automation
Gerrit-Reviewer: Kevin Harwell <kharwell at digium.com>
Gerrit-CC: Joshua Colp <jcolp at sangoma.com>
Gerrit-MessageType: merged
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20211202/600ca1a3/attachment-0001.html>

More information about the asterisk-code-review mailing list