[asterisk-bugs] [JIRA] (ASTERISK-29732) progdocs: Fix grouping for latest Doxygen

[Alexander Traud (JIRA)]

Alexander Traud created ASTERISK-29732:
------------------------------------------

             Summary: progdocs: Fix grouping for latest Doxygen
                 Key: ASTERISK-29732
                 URL: https://issues.asterisk.org/jira/browse/ASTERISK-29732
             Project: Asterisk
          Issue Type: Bug
      Security Level: None
          Components: Documentation
    Affects Versions: 19.0.0, 18.8.0, 16.22.0
            Reporter: Alexander Traud
            Severity: Trivial


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.



--
This message was sent by Atlassian JIRA
(v6.2#6252)