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

[Alexander Traud (JIRA)]

Alexander Traud created ASTERISK-29779:
------------------------------------------

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


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)