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

[Alexander Traud (JIRA)]

Alexander Traud created ASTERISK-29765:
------------------------------------------

             Summary: 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: 19.0.0, 18.8.0, 16.22.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)