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

[Alexander Traud (JIRA)]

Alexander Traud created ASTERISK-29734:
------------------------------------------

             Summary: 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: 19.0.0, 18.8.0, 16.22.0
            Reporter: Alexander Traud
            Severity: Trivial
         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)