[asterisk-bugs] [JIRA] (ASTERISK-29765) xmldoc: Fix for Doxygen

Sat Nov 20 06:20:50 CST 2021

    [ https://issues.asterisk.org/jira/browse/ASTERISK-29765?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=257105#comment-257105 ] 

Asterisk Team commented on ASTERISK-29765:
------------------------------------------

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/].

> xmldoc: Fix for Doxygen
> -----------------------
>
>                 Key: ASTERISK-29765
>                 URL: https://issues.asterisk.org/jira/browse/ASTERISK-29765
>             Project: Asterisk
>          Issue Type: Bug
>      Security Level: None
>          Components: Documentation
>    Affects Versions: 16.22.0, 18.8.0, 19.0.0
>            Reporter: Alexander Traud
>            Severity: Trivial
>
> One more thing, affecting optional modules. Since Asterisk 1.6.2, the XML documentation is [enabled on default|https://github.com/asterisk/asterisk/commit/5b168ee]. However, I disabled that via {{./configure --disable-xmldoc}} normally. Therefore, my Doxygen did not parse source code protected by the {{#ifdef AST_XML_DOCS}}. If enabled and if all {{WARN_}} are enabled in the file {{doc/asterisk-ng-doxygen.in}}, the following appears in the file {{doxygen.log}}:
> {code}
> main/xmldoc.c:1459: warning: Unsupported xml/html tag <argument> found
> main/xmldoc.c:875: warning: Unsupported xml/html tag <parameter> found
> main/xmldoc.c:1720: warning: Unsupported xml/html tag <enum> found
> main/xmldoc.c:1754: warning: Unsupported xml/html tag <enumlist> found
> main/xmldoc.c:1791: warning: Unsupported xml/html tag <option> found
> main/xmldoc.c:1838: warning: Unsupported xml/html tag <optionlist> found
> main/xmldoc.c:1505: warning: Unsupported xml/html tag <variable> found
> main/xmldoc.c:1505: warning: Unsupported xml/html tag <variablelist> found
> main/xmldoc.c:1566: warning: Unsupported xml/html tag <variablelist> found
> main/xmldoc.c:1459: warning: Unsupported xml/html tag <argument> found
> main/xmldoc.c:875: warning: Unsupported xml/html tag <parameter> found
> main/xmldoc.c:1720: warning: Unsupported xml/html tag <enum> found
> main/xmldoc.c:1754: warning: Unsupported xml/html tag <enumlist> found
> main/xmldoc.c:1791: warning: Unsupported xml/html tag <option> found
> main/xmldoc.c:1838: warning: Unsupported xml/html tag <optionlist> found
> main/xmldoc.c:1505: warning: Unsupported xml/html tag <variable> found
> main/xmldoc.c:1505: warning: Unsupported xml/html tag <variablelist> found
> main/xmldoc.c:1566: warning: Unsupported xml/html tag <variablelist> found
> main/xmldoc.c:1202: warning: argument 'node' of command @param is not found in the argument list of _ast_xmldoc_build_syntax(struct ast_xml_node *root_node, const char *type, const char *name)
> main/xmldoc.c:1216: warning: The following parameter of _ast_xmldoc_build_syntax(struct ast_xml_node *root_node, const char *type, const char *name) is not documented:
>   parameter 'root_node'
> include/asterisk/xmldoc.h:83: warning: argument 'query' of command @param is not found in the argument list of ast_xmldoc_query(const char *fmt,...)
> main/xmldoc.c:2545: warning: The following parameter of ast_xmldoc_query(const char *fmt,...) is not documented:
>   parameter 'fmt'
> main/xmldoc.c:2094: warning: Unsupported xml/html tag <variablelist> found
> main/xmldoc.c:2093: warning: argument 'raw' of command @param is not found in the argument list of xmldoc_get_formatted(struct ast_xml_node *node, int raw_output, int raw_wrap)
> main/xmldoc.c:2103: warning: The following parameter of xmldoc_get_formatted(struct ast_xml_node *node, int raw_output, int raw_wrap) is not documented:
>   parameter 'raw_output'
> main/xmldoc.c:925: warning: Unsupported xml/html tag <syntax> found
> main/xmldoc.c:932: warning: return value 'On' of xmldoc_get_syntax_cmd has multiple documentation sections
> main/xmldoc.c:559: warning: argument 'node' of command @param is not found in the argument list of xmldoc_has_inside(struct ast_xml_node *fixnode, const char *what)
> main/xmldoc.c:568: warning: The following parameter of xmldoc_has_inside(struct ast_xml_node *fixnode, const char *what) is not documented:
>   parameter 'fixnode'
> main/xmldoc.c:581: warning: argument 'node' of command @param is not found in the argument list of xmldoc_has_nodes(struct ast_xml_node *fixnode)
> main/xmldoc.c:589: warning: The following parameter of xmldoc_has_nodes(struct ast_xml_node *fixnode) is not documented:
>   parameter 'fixnode'
> main/xmldoc.c:602: warning: argument 'node' of command @param is not found in the argument list of xmldoc_has_specialtags(struct ast_xml_node *fixnode)
> main/xmldoc.c:610: warning: The following parameter of xmldoc_has_specialtags(struct ast_xml_node *fixnode) is not documented:
>   parameter 'fixnode'
> main/xmldoc.c:1459: warning: Unsupported xml/html tag <argument> found
> main/xmldoc.c:1462: warning: Unsupported xml/html tag <argument> found
> main/xmldoc.c:1462: warning: Unsupported xml/html tag <parameter> found
> main/xmldoc.c:1465: warning: Unsupported xml/html tag <argument> found
> main/xmldoc.c:875: warning: Unsupported xml/html tag <parameter> found
> main/xmldoc.c:877: warning: Unsupported xml/html tag <enumlist> found
> main/xmldoc.c:1720: warning: Unsupported xml/html tag <enum> found
> main/xmldoc.c:1722: warning: Unsupported xml/html tag <enum> found
> main/xmldoc.c:1728: warning: The following parameter of xmldoc_parse_enum(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer) is not documented:
>   parameter 'tabs'
> main/xmldoc.c:1754: warning: Unsupported xml/html tag <enumlist> found
> main/xmldoc.c:1756: warning: Unsupported xml/html tag <enumlist> found
> main/xmldoc.c:1759: warning: Unsupported xml/html tag <enumlist> found
> main/xmldoc.c:1760: warning: Unsupported xml/html tag <enumlist> found
> main/xmldoc.c:1762: warning: The following parameter of xmldoc_parse_enumlist(struct ast_xml_node *fixnode, const char *tabs, struct ast_str **buffer) is not documented:
>   parameter 'tabs'
> main/xmldoc.c:1968: warning: argument 'String' of command @param is not found in the argument list of xmldoc_parse_info(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
> main/xmldoc.c:1981: warning: The following parameter of xmldoc_parse_info(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer) is not documented:
>   parameter 'buffer'
> main/xmldoc.c:1791: warning: Unsupported xml/html tag <option> found
> main/xmldoc.c:1793: warning: Unsupported xml/html tag <option> found
> main/xmldoc.c:1838: warning: Unsupported xml/html tag <optionlist> found
> main/xmldoc.c:1505: warning: Unsupported xml/html tag <variable> found
> main/xmldoc.c:1505: warning: Unsupported xml/html tag <variablelist> found
> main/xmldoc.c:1566: warning: Unsupported xml/html tag <variablelist> found
> main/xmldoc.c:1575: warning: Unsupported xml/html tag <variablelist> found
> main/xmldoc.c:359: warning: Found unknown command '\r'
> include/asterisk/xmldoc.h:83: warning: argument 'query' of command @param is not found in the argument list of ast_xmldoc_query(const char *fmt,...)
> include/asterisk/xmldoc.h:91: warning: The following parameter of ast_xmldoc_query(const char *fmt,...) is not documented:
>   parameter 'fmt'
> {code}I fixed only those syntactic issues. I did not harmonize the semantic level. For example, I had to add the parameter description for ‘tabs’, looked-up the existing descriptions and found eight different ones:
> # Add this string before the content of the parsed element.
> # Added this string before the content of the \<xyz\> element.
> # put tabs before printing the node content.
> # What to be printed before the argument name.
> # A string to be appended at the beginning of the output that will be stored in buffer.
> # A string to be appended at the beginning of each line being added to the buffer string.
> # A string to be appended at the beginning of each line being printed inside 'buffer'.
> # A string to be appended at the beginning of each line being printed inside 'buffer'
> Similar about general *wording*: Sometimes ‘node’, ‘tag’ or ‘element’ is used.
> Similar about *grammar*: Sometimes the descriptions end with a period, sometimes not.
> Similar about *presentation*: Sometimes {{<}} is used around the name, sometimes {{'}}, sometimes nothing.
> Consequently, this module for the XML documentation, is a great example what gets wrong when one is not consistent, one important puzzle piece while writing documentation (beside _not_ explaining the obvious) … perfect job for (hiring, or at least consulting) a professional technical writer.

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