[asterisk-dev] [Code Review] 3812: AMI: Allow for response documentation

[Matt Jordan]

> On July 17, 2014, 12:37 p.m., Corey Farrell wrote:
> > trunk/doc/appdocsxml.dtd, line 34
> > <https://reviewboard.asterisk.org/r/3812/diff/2/?file=64572#file64572line34>
> >
> >     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.

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.


- Matt


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


On July 16, 2014, 4:16 p.m., opticron wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviewboard.asterisk.org/r/3812/
> -----------------------------------------------------------
> 
> (Updated July 16, 2014, 4:16 p.m.)
> 
> 
> Review request for Asterisk Developers.
> 
> 
> Repository: Asterisk
> 
> 
> Description
> -------
> 
> 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.
> 
> 
> Diffs
> -----
> 
>   trunk/main/xmldoc.c 418779 
>   trunk/main/manager_bridges.c 418779 
>   trunk/main/manager.c 418779 
>   trunk/include/asterisk/xmldoc.h 418779 
>   trunk/include/asterisk/manager.h 418779 
>   trunk/doc/appdocsxml.dtd 418779 
> 
> Diff: https://reviewboard.asterisk.org/r/3812/diff/
> 
> 
> Testing
> -------
> 
> The BridgeInfo AMI command was documented and tested as an example.
> 
> 
> Thanks,
> 
> opticron
> 
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20140717/8da48b4b/attachment-0001.html>