[asterisk-bugs] [JIRA] (ASTERISK-29734) progdocs: Use Doxygen \example correctly

[Asterisk Team (JIRA)]

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

Asterisk Team updated ASTERISK-29734:
-------------------------------------

    Target Release Version/s: 20.0.0

> progdocs: Use Doxygen \example correctly
> ----------------------------------------
>
>                 Key: ASTERISK-29734
>                 URL: https://issues.asterisk.org/jira/browse/ASTERISK-29734
>             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
>      Target Release: 16.23.0, 18.9.0, 19.1.0, 20.0.0
>
>         Attachments: doxygen_example.patch
>
>
> {code}
> sudo apt install doxygen
> make progdocs
> {code}
> gives a warning in the file {{doxygen.log}}:
> {code}
> include/asterisk/strings.h:1126: warning: Example include/asterisk/strings.h was already documented. Ignoring documentation found here.
> {code}
> because {{strings.h}} contains the command {{\example}} twice. In other words, Doxygen adds the (whole) current file verbatim as source code. This makes sense only once.
> Actually, the author of that documentation made a typo and instead meant the command {{\code}}. This warning message revealed another code section which is not declared as such.
> Furthermore, with a grep project wide, another {{\example}} vs. {{\code}} was found. Finally, the only valid use of {{\example}} turned out to be a misuse as well.
> All this is fixed by the attached patch.



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