[asterisk-bugs] [JIRA] (ASTERISK-29779) progdocs: Hidden code sections with syntax errors.

[Asterisk Team (JIRA)]

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

Asterisk Team updated ASTERISK-29779:
-------------------------------------

    Target Release Version/s: 20.0.0

> progdocs: Hidden code sections with syntax errors.
> --------------------------------------------------
>
>                 Key: ASTERISK-29779
>                 URL: https://issues.asterisk.org/jira/browse/ASTERISK-29779
>             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
>      Target Release: 16.23.0, 18.9.0, 19.1.0, 20.0.0
>
>
> When running {{make progdocs}}, Doxygen reports warnings in the file {{doxygen.log}}. While analyzing their cause, sometimes, a common pattern revealed, for example, many void functions had “{{\return Nothing}}” documented. While this is OK for a human reader, Doxygen is not able to differ that from a copy-and-paste error like “{{\retval 1 Success}}” for a void function. Therefore, silencing all those warnings made sense, so in future, when someone wants to syntax-check his Doxygen documentation, he sees not 2369 warning but just his warnings.
> After silencing those warnings, many of those search patterns could still be found in source code: Doxygen did not see/parse some Doxygen comments. The causes are:
> * [{{WARN_IF_DOC_ERROR}}|https://www.doxygen.nl/manual/config.html#cfg_warn_if_doc_error]
> In Doxygen, this configuration option is enabled on default but was disabled nine years ago in Asterisk. It go re-enabled.
> * [{{INTERNAL_DOCS}}|https://www.doxygen.nl/manual/config.html#cfg_internal_docs]
> This was disabled but gets enabled in the developer mode of Asterisk, now.
> * [{{EXTRACT_STATIC}}|https://www.doxygen.nl/manual/config.html#cfg_extract_static]
> In Doxygen, this configuration option is disabled on default but was already enabled in Asterisk.
> * [{{ENABLE_PREPROCESSING}}|https://www.doxygen.nl/manual/config.html#cfg_enable_preprocessing].
> The latter turned out to be a problem in Asterisk: If a code section is guarded with an {{#ifdef}}, Doxygen might not look into that section. To find syntax errors there, I disabled preprocessing in a test run. The following defines then showed errors:
> * {{OPTIONAL_API}}
> Enabled in {{menuselect}} on default, still not parsed by Doxygen.
> * {{AO2_DEBUG}}
> * {{MALLOC_DEBUG}}
> * {{AST_DEVMODE}}
> * {{TEST_FRAMEWORK}}
> * {{PJ_HAS_SSL_SOCK}}
> * {{HAVE_SS7}}, {{HAVE_PRI}}, and {{THRESHOLD_DEVSTATE_PLACEHOLDER}}.
> Although with the latter, I am not sure, if those would work. It looks like defines created by the script {{./configure}} work. Defines created by {{menuselect}} do not work.
> Furthermore, the source code contains alternative defines like {{ODBC_STORAGE}} and {{IMAP_STORAGE}}. All those can be set individually in Doxygen, for example, via {{PREDEFINED:=OPTIONAL_API}}.
> Beside that, the search pattern
> {code}
> /\*[*\s]*\\
> {code}
> revealed special comment sections which missed the explanation mark at start {{/*!}}. Because of that, Doxygen does not parse that section and therefore creates no warning at all.
> Beside that, the search pattern
> {code}
> [ !*][^\\@]param 
> {code}
> revealed brief, parameter, and retval commands which did start with a space or a normal slash but not with the required backslash.
> Beside that, the search pattern
> {code}
> \\[rR]et[uv][ra][nl] [^ ]*,
> {code}
> revealed retval commands with more than one parameter. Because of the comma, Doxygen thinks the next word is a parameter for retval as well. Therefore, a comma after the only parameter must be avoided.
> Because Doxygen was now able to see those sections, further syntax errors could be fixed. At the end, the source code still contained some {{\return Nothing}}. Investigation of those revealed [two|https://github.com/doxygen/doxygen/issues/8905] [bugs|https://github.com/doxygen/doxygen/issues/8914] and [one enhancement|https://github.com/doxygen/doxygen/issues/8919] in Doxygen itself.
> Long story short, this issue here fixes those syntax errors which Doxygen was not able to find without further help. Although those hidden sections are real nit-pick, they helped to remove common issues (which might confuse future documentation because of copy-and-paste errors) and the deeper investigation revealed limitations of Doxygen itself.
> Perhaps some of those section could be added to {{PREDEFINED}} in the Doxygen configuration file. I cannot judge on that, therefore I leave it as is.



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