Summary:	ASTERISK-29779: progdocs: Hidden code sections with syntax errors.
Reporter:	Alexander Traud (traud)	Labels:
Date Opened:	2021-11-28 04:19:57.000-0600	Date Closed:	2021-12-02 10:37:40.000-0600
Priority:	Trivial	Regression?
Status:	Closed/Complete	Components:	Documentation
Versions:	16.22.0 18.8.0 19.0.0	Frequency of Occurrence
Related Issues:
Environment:		Attachments:
Description:	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.
Comments:	By: Asterisk Team (asteriskteam) 2021-11-28 04:19:59.815-0600 Thanks for creating a report! The issue has entered the triage process. That means the issue will wait in this status until a Bug Marshal has an opportunity to review the issue. Once the issue has been reviewed you will receive comments regarding the next steps towards resolution. Please note that log messages and other files should not be sent to the Sangoma Asterisk Team unless explicitly asked for. All files should be placed on this issue in a sanitized fashion as needed. A good first step is for you to review the [Asterisk Issue Guidelines|https://wiki.asterisk.org/wiki/display/AST/Asterisk+Issue+Guidelines] if you haven't already. The guidelines detail what is expected from an Asterisk issue report. Then, if you are submitting a patch, please review the [Patch Contribution Process|https://wiki.asterisk.org/wiki/display/AST/Patch+Contribution+Process]. Please note that once your issue enters an open state it has been accepted. As Asterisk is an open source project there is no guarantee or timeframe on when your issue will be looked into. If you need expedient resolution you will need to find and pay a suitable developer. Asking for an update on your issue will not yield any progress on it and will not result in a response. All updates are posted to the issue when they occur. Please note that by submitting data, code, or documentation to Sangoma through JIRA, you accept the Terms of Use present at [https://www.asterisk.org/terms-of-use/|https://www.asterisk.org/terms-of-use/]. By: Friendly Automation (friendly-automation) 2021-12-02 10:37:41.465-0600 Change 17587 merged by Kevin Harwell: progdocs: Fix for Doxygen, the hidden parts. [https://gerrit.asterisk.org/c/asterisk/+/17587|https://gerrit.asterisk.org/c/asterisk/+/17587] By: Friendly Automation (friendly-automation) 2021-12-02 10:37:53.879-0600 Change 17603 merged by Kevin Harwell: progdocs: Fix for Doxygen, the hidden parts. [https://gerrit.asterisk.org/c/asterisk/+/17603|https://gerrit.asterisk.org/c/asterisk/+/17603] By: Friendly Automation (friendly-automation) 2021-12-02 10:38:08.043-0600 Change 17602 merged by Kevin Harwell: progdocs: Fix for Doxygen, the hidden parts. [https://gerrit.asterisk.org/c/asterisk/+/17602|https://gerrit.asterisk.org/c/asterisk/+/17602] By: Friendly Automation (friendly-automation) 2021-12-02 10:38:27.311-0600 Change 17588 merged by Kevin Harwell: progdocs: Fix for Doxygen, the hidden parts. [https://gerrit.asterisk.org/c/asterisk/+/17588|https://gerrit.asterisk.org/c/asterisk/+/17588]