<html>
<body>
<div style="font-family: Verdana, Arial, Helvetica, Sans-Serif;">
<table bgcolor="#f9f3c9" width="100%" cellpadding="8" style="border: 1px #c9c399 solid;">
<tr>
<td>
This is an automatically generated e-mail. To reply, visit:
<a href="https://reviewboard.asterisk.org/r/2058/">https://reviewboard.asterisk.org/r/2058/</a>
</td>
</tr>
</table>
<br />
<div>
<table width="100%" border="0" bgcolor="white" style="border: 1px solid #C0C0C0; border-collapse: collapse; margin: 2px padding: 2px;">
<thead>
<tr>
<th colspan="4" bgcolor="#F0F0F0" style="border-bottom: 1px solid #C0C0C0; font-size: 9pt; padding: 4px 8px; text-align: left;">
<a href="https://reviewboard.asterisk.org/r/2058/diff/4/?file=30980#file30980line5" style="color: black; font-weight: bold; text-decoration: underline;">/trunk/doc/appdocsxml.dtd</a>
<span style="font-weight: normal;">
(Diff revision 4)
</span>
</th>
</tr>
</thead>
<tbody style="background-color: #e4d9cb; padding: 4px 8px; text-align: center;">
<tr>
<td colspan="4"><pre style="font-size: 8pt; line-height: 140%; margin: 0; "></pre></td>
</tr>
</tbody>
<tbody>
<tr>
<th bgcolor="#f0f0f0" style="border-right: 1px solid #C0C0C0;" align="right"><font size="2">5</font></th>
<td bgcolor="#ffffff" width="50%"><pre style="font-size: 8pt; line-height: 140%; margin: 0; "> <!ATTLIST xi:include<span class="ew"> </span></pre></td>
<th bgcolor="#f0f0f0" style="border-left: 1px solid #C0C0C0; border-right: 1px solid #C0C0C0;" align="right"><font size="2">5</font></th>
<td bgcolor="#ffffff" width="50%"><pre style="font-size: 8pt; line-height: 140%; margin: 0; "> <!ATTLIST xi:include<span class="ew"> </span></pre></td>
</tr>
</tbody>
</table>
<pre style="margin-left: 2em; white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;">red blob</pre>
</div>
<br />
<div>
<table width="100%" border="0" bgcolor="white" style="border: 1px solid #C0C0C0; border-collapse: collapse; margin: 2px padding: 2px;">
<thead>
<tr>
<th colspan="4" bgcolor="#F0F0F0" style="border-bottom: 1px solid #C0C0C0; font-size: 9pt; padding: 4px 8px; text-align: left;">
<a href="https://reviewboard.asterisk.org/r/2058/diff/4/?file=30986#file30986line292" style="color: black; font-weight: bold; text-decoration: underline;">/trunk/main/config_options.c</a>
<span style="font-weight: normal;">
(Diff revision 4)
</span>
</th>
</tr>
</thead>
<tbody style="background-color: #e4d9cb; padding: 4px 8px; text-align: center;">
<tr>
<td colspan="4"><pre style="font-size: 8pt; line-height: 140%; margin: 0; ">int __aco_option_register(struct aco_info *info, const char *name, enum aco_matchtype matchtype, struct aco_type **types,</pre></td>
</tr>
</tbody>
<tbody>
<tr>
<th bgcolor="#b1ebb0" style="border-right: 1px solid #C0C0C0;" align="right"><font size="2"></font></th>
<td bgcolor="#c5ffc4" width="50%"><pre style="font-size: 8pt; line-height: 140%; margin: 0; "></pre></td>
<th bgcolor="#b1ebb0" style="border-left: 1px solid #C0C0C0; border-right: 1px solid #C0C0C0;" align="right"><font size="2">292</font></th>
<td bgcolor="#c5ffc4" width="50%"><pre style="font-size: 8pt; line-height: 140%; margin: 0; "> <span class="cm">/* </span><span class="cs">XXX</span><span class="cm"> If no documentation has been registered, fail with warning */</span></pre></td>
</tr>
</tbody>
</table>
<pre style="margin-left: 2em; white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;">This seems to be done below. This comment (or just the XXX) can be removed.</pre>
</div>
<br />
<p>- opticron</p>
<br />
<p>On August 16th, 2012, 1:58 p.m., Terry Wilson wrote:</p>
<table bgcolor="#fefadf" width="100%" cellspacing="0" cellpadding="8" style="background-image: url('https://reviewboard.asterisk.org/media/rb/images/review_request_box_top_bg.png'); background-position: left top; background-repeat: repeat-x; border: 1px black solid;">
<tr>
<td>
<div>Review request for Asterisk Developers and Matt Jordan.</div>
<div>By Terry Wilson.</div>
<p style="color: grey;"><i>Updated Aug. 16, 2012, 1:58 p.m.</i></p>
<h1 style="color: #575012; font-size: 10pt; margin-top: 1.5em;">Description </h1>
<table width="100%" bgcolor="#ffffff" cellspacing="0" cellpadding="10" style="border: 1px solid #b8b5a0">
<tr>
<td>
<pre style="margin: 0; padding: 0; white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;">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.</pre>
</td>
</tr>
</table>
<h1 style="color: #575012; font-size: 10pt; margin-top: 1.5em;">Testing </h1>
<table width="100%" bgcolor="#ffffff" cellspacing="0" cellpadding="10" style="border: 1px solid #b8b5a0">
<tr>
<td>
<pre style="margin: 0; padding: 0; white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;">tested CLI commands.</pre>
</td>
</tr>
</table>
<h1 style="color: #575012; font-size: 10pt; margin-top: 1.5em;">Diffs</b> </h1>
<ul style="margin-left: 3em; padding-left: 0;">
<li>/trunk/apps/app_skel.c <span style="color: grey">(371344)</span></li>
<li>/trunk/doc/appdocsxml.dtd <span style="color: grey">(371344)</span></li>
<li>/trunk/include/asterisk/_private.h <span style="color: grey">(371344)</span></li>
<li>/trunk/include/asterisk/config_options.h <span style="color: grey">(371344)</span></li>
<li>/trunk/include/asterisk/xml.h <span style="color: grey">(371344)</span></li>
<li>/trunk/include/asterisk/xmldoc.h <span style="color: grey">(371344)</span></li>
<li>/trunk/main/asterisk.c <span style="color: grey">(371344)</span></li>
<li>/trunk/main/config_options.c <span style="color: grey">(371344)</span></li>
<li>/trunk/main/xml.c <span style="color: grey">(371344)</span></li>
<li>/trunk/main/xmldoc.c <span style="color: grey">(371344)</span></li>
</ul>
<p><a href="https://reviewboard.asterisk.org/r/2058/diff/" style="margin-left: 3em;">View Diff</a></p>
</td>
</tr>
</table>
</div>
</body>
</html>