[asterisk-dev] [Code Review] Add xmldoc for config options, along with some CLI commands for viewing config option-related stuff

[Terry Wilson]

-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviewboard.asterisk.org/r/2058/
-----------------------------------------------------------

Review request for Asterisk Developers and Matt Jordan.


Summary
-------

This patch kind of shoe-horns config option documentation into the current xmldoc stuff. It is currently proof-of-concept level code and needs to be cleaned up. I'd really like some feedback on how this should really go. I've changed my mind and re-written things several times now.

What it does:
1. Uses the ast_xml_doc_item stuff for manager events to store synopsis, description, and very limited syntax information about config items
2. Adds CLI functions config show option(s)/type(s) to display some limited info from the XML docs
3. Checks that, if XML_DOCS are enabled, that there is XML documentation for an option being registered (it currently doesn't return -1 if missing since I've only added docs for app_skel)

What it still needs:
1. It needs to record more information that is available in the xmldocs in the ast_xml_doc_item (defaults, type fields for objects, valid ranges for values, etc.)
2. The CLI output is ugly and just mostly place-holder text displaying the values. It needs to be made more consistent with other output.
3. More descriptions should be added with the appropriate formatting, etc.

What I wish we were doing instead:
1. Writing little parsers of the XML data to store raw text in the ast_xml_doc_item to output to the CLI is...suboptimal. We have XML data. We should use XSLT to transform the XML data into CLI output, manager output, or whatever we need. This would also make it easier to make language-neutral output since the "syntax" info relies on things like the word "category", whether or not a regex matches or does not match, type fields, etc.

2. Some information is duplicated in the XML docs and in the aco_option_register() arguments. xmldocs are optional, so you can't remove the arguments from aco_option_register. Having  aco_option_register generate the XML and apply it to the in-memory xmldocs at runtime with a command to dump the updated XML would be a solution to removing the duplication and still being able to generate complete xml documentation for translating to the wiki, etc.

This is an attempt to get something in for Asterisk 11, even if it isn't (anywhere near) perfect. I just don't want to spend even more time cleaning up stuff if we decide to change the design a lot. There are some red blobs that need cleaning up, etc. as well.


Diffs
-----

  /trunk/apps/app_skel.c 370233 
  /trunk/doc/appdocsxml.dtd 370233 
  /trunk/include/asterisk/_private.h 370233 
  /trunk/include/asterisk/config_options.h 370233 
  /trunk/include/asterisk/xmldoc.h 370233 
  /trunk/main/asterisk.c 370233 
  /trunk/main/config_options.c 370233 
  /trunk/main/xmldoc.c 370233 

Diff: https://reviewboard.asterisk.org/r/2058/diff


Testing
-------

tested CLI commands.


Thanks,

Terry

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20120719/b70b2311/attachment-0001.htm>