<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/3812/">https://reviewboard.asterisk.org/r/3812/</a>
</td>
</tr>
</table>
<br />
<blockquote style="margin-left: 1em; border-left: 2px solid #d0d0d0; padding-left: 10px;">
<p style="margin-top: 0;">On July 17th, 2014, 12:37 p.m. CDT, <b>Corey Farrell</b> wrote:</p>
<blockquote style="margin-left: 1em; border-left: 2px solid #d0d0d0; padding-left: 10px;">
<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/3812/diff/2/?file=64572#file64572line34" style="color: black; font-weight: bold; text-decoration: underline;">trunk/doc/appdocsxml.dtd</a>
<span style="font-weight: normal;">
(Diff revision 2)
</span>
</th>
</tr>
</thead>
<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">34</font></th>
<td bgcolor="#c5ffc4" width="50%"><pre style="font-size: 8pt; line-height: 140%; margin: 0; "> <span class="k"><!ELEMENT</span> <span class="nt">responses</span> <span class="o">(</span><span class="nt">managerEvent</span><span class="o">+|</span><span class="nt">xi:include</span><span class="o">+)</span><span class="k">></span></pre></td>
</tr>
</tbody>
</table>
<pre style="white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;">I'd prefer to see a new xml tag for responses instead of managerEvent. The BridgeInfo responses are actually a good example of why. This should allow us to document the fact that BridgeInfoChannel is a list item, and BridgeInfoComplete is the final packet / end of list. I'm sure we'll find other reasons to have different attributes/tags within action responses vs managerEvent, but list responses are the big reason I can think of. I'm sure there will be similarities, but that's what ATTLIST is for.</pre>
</blockquote>
</blockquote>
<pre style="margin-left: 1em; white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;">Well.. except that it won't always work out well that way.
Certain actions actually cause a sequence of events to be issued as part of their response. This occurs in particular when a Stasis message type has a to_ami handler, and that message type is actually a cached snapshot message type. When an action is executed that queries the cache for those objects, it will construct the AMI responses to its action using that to_ami callback. That will result in full AMI events being generated for the action.
Which means, of course, that the action returns what the eventInstance documents.
I'd prefer to not have two XML nodes document the same thing: that kind of redundancy just increases the amount of work that documenters have to do (which leads to not having documentation). Instead, an action documentation should be able to reference an existing eventInstance if what it generates are those events in its response.
If that means we need to enhance the schema for eventInstances to note whether or not they are documenting a response to an action that's fine.</pre>
<br />
<p>- Matt</p>
<br />
<p>On July 16th, 2014, 4:16 p.m. CDT, opticron wrote:</p>
<table bgcolor="#fefadf" width="100%" cellspacing="0" cellpadding="8" style="background-image: url('https://reviewboard.asterisk.org/static/rb/images/review_request_box_top_bg.ab6f3b1072c9.png'); background-position: left top; background-repeat: repeat-x; border: 1px black solid;">
<tr>
<td>
<div>Review request for Asterisk Developers.</div>
<div>By opticron.</div>
<p style="color: grey;"><i>Updated July 16, 2014, 4:16 p.m.</i></p>
<div style="margin-top: 1.5em;">
<b style="color: #575012; font-size: 10pt;">Repository: </b>
Asterisk
</div>
<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;">Allow for responses to AMI actions/commands to be documented properly in XML and displayed via the CLI. Response events are documented exactly as standard AMI events are documented.</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;">The BridgeInfo AMI command was documented and tested as an example.</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/main/xmldoc.c <span style="color: grey">(418779)</span></li>
<li>trunk/main/manager_bridges.c <span style="color: grey">(418779)</span></li>
<li>trunk/main/manager.c <span style="color: grey">(418779)</span></li>
<li>trunk/include/asterisk/xmldoc.h <span style="color: grey">(418779)</span></li>
<li>trunk/include/asterisk/manager.h <span style="color: grey">(418779)</span></li>
<li>trunk/doc/appdocsxml.dtd <span style="color: grey">(418779)</span></li>
</ul>
<p><a href="https://reviewboard.asterisk.org/r/3812/diff/" style="margin-left: 3em;">View Diff</a></p>
</td>
</tr>
</table>
</div>
</body>
</html>