Summary:	ASTERISK-29732: progdocs: Fix grouping for latest Doxygen
Reporter:	Alexander Traud (traud)	Labels:	patch
Date Opened:	2021-11-12 10:04:35.000-0600	Date Closed:	2021-12-02 10:16:06.000-0600
Priority:	Trivial	Regression?
Status:	Closed/Complete	Components:	Documentation
Versions:	16.22.0 18.8.0 19.0.0	Frequency of Occurrence
Related Issues:
Environment:		Attachments:	( 0) doxygen.patch
Description:	Since Doxygen 1.8.16, opening and closing a group must not be done as C comment but as Doxygen [special comment block|https://www.doxygen.nl/manual/docblocks.html#specialblock]. In other words, not just one asterisk but also an explanation mark is required so that Doxygen finds a group. Because the previous behavior was just a coincidence, such a wrong grouping does not give any error or warning. The issue was found in another project which had totally broken HTML documentation because of this. Places in code were found with: {code} grep -r '[^/]/[/*]\s*@}' {code} While testing {code} sudo apt install doxygen make progdocs {code} the file {{doxygen.log}} is created. Warnings are not printed to the Terminal but only to that file. That revealed several further grouping errors, like a closed group without opening it, or a opened group which was never closed. {code} channels/chan_sip.c:886: warning: unbalanced grouping commands include/asterisk/app.h:1509: warning: unbalanced grouping commands include/asterisk/astmm.h:318: warning: end of file with unbalanced grouping commands include/asterisk/mwi.h:581: warning: end of file while inside a group include/asterisk/pbx.h:1404: warning: unbalanced grouping commands include/asterisk/pbx.h:1442: warning: unbalanced grouping commands include/asterisk/rtp_engine.h:2908: warning: end of file while inside a group include/asterisk/stasis_app_mailbox.h:92: warning: end of file with unbalanced grouping commands {code} The attached patch fixes all found (via grep) and reported (as warning) grouping issues.
Comments:	By: Asterisk Team (asteriskteam) 2021-11-12 10:04:36.589-0600 Thanks for creating a report! The issue has entered the triage process. That means the issue will wait in this status until a Bug Marshal has an opportunity to review the issue. Once the issue has been reviewed you will receive comments regarding the next steps towards resolution. Please note that log messages and other files should not be sent to the Sangoma Asterisk Team unless explicitly asked for. All files should be placed on this issue in a sanitized fashion as needed. A good first step is for you to review the [Asterisk Issue Guidelines|https://wiki.asterisk.org/wiki/display/AST/Asterisk+Issue+Guidelines] if you haven't already. The guidelines detail what is expected from an Asterisk issue report. Then, if you are submitting a patch, please review the [Patch Contribution Process|https://wiki.asterisk.org/wiki/display/AST/Patch+Contribution+Process]. Please note that once your issue enters an open state it has been accepted. As Asterisk is an open source project there is no guarantee or timeframe on when your issue will be looked into. If you need expedient resolution you will need to find and pay a suitable developer. Asking for an update on your issue will not yield any progress on it and will not result in a response. All updates are posted to the issue when they occur. Please note that by submitting data, code, or documentation to Sangoma through JIRA, you accept the Terms of Use present at [https://www.asterisk.org/terms-of-use/|https://www.asterisk.org/terms-of-use/]. By: Friendly Automation (friendly-automation) 2021-12-02 10:16:07.415-0600 Change 17345 merged by Friendly Automation: progdocs: Fix grouping for latest Doxygen. [https://gerrit.asterisk.org/c/asterisk/+/17345|https://gerrit.asterisk.org/c/asterisk/+/17345] By: Friendly Automation (friendly-automation) 2021-12-02 10:25:42.587-0600 Change 17335 merged by Kevin Harwell: progdocs: Fix grouping for latest Doxygen. [https://gerrit.asterisk.org/c/asterisk/+/17335|https://gerrit.asterisk.org/c/asterisk/+/17335] By: Friendly Automation (friendly-automation) 2021-12-02 10:25:55.679-0600 Change 17346 merged by Kevin Harwell: progdocs: Fix grouping for latest Doxygen. [https://gerrit.asterisk.org/c/asterisk/+/17346|https://gerrit.asterisk.org/c/asterisk/+/17346] By: Friendly Automation (friendly-automation) 2021-12-02 10:26:11.294-0600 Change 17334 merged by Kevin Harwell: progdocs: Fix grouping for latest Doxygen. [https://gerrit.asterisk.org/c/asterisk/+/17334|https://gerrit.asterisk.org/c/asterisk/+/17334]