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

[Kevin Harwell (JIRA)]

     [ https://issues.asterisk.org/jira/browse/ASTERISK-29732?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Kevin Harwell updated ASTERISK-29732:
-------------------------------------

    Assignee: Alexander Traud

> 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: 16.22.0, 18.8.0, 19.0.0
>            Reporter: Alexander Traud
>            Assignee: Alexander Traud
>            Severity: Trivial
>              Labels: patch
>         Attachments: doxygen.patch
>
>
> 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)