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

[Asterisk Team (JIRA)]

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

Asterisk Team updated ASTERISK-29765:
-------------------------------------

    Target Release Version/s: 19.1.0

> 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
>            Assignee: Alexander Traud
>            Severity: Trivial
>      Target Release: 16.23.0, 18.9.0, 19.1.0
>
>
> 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)