> On July 17, 2014, 1: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. > > Matt Jordan wrote: > 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.
As long as we can make this capable of documenting action specific stuff, I'm fine with that. I do think the responses that produce list items + listend should have some kind of notation to indicate their purpose. This finding can be closed. - Corey ----------------------------------------------------------- This is an automatically generated e-mail. To reply, visit: https://reviewboard.asterisk.org/r/3812/#review12718 ----------------------------------------------------------- On July 16, 2014, 5: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, 5: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 > >
-- _____________________________________________________________________ -- Bandwidth and Colocation Provided by http://www.api-digital.com -- asterisk-dev mailing list To UNSUBSCRIBE or update options visit: http://lists.digium.com/mailman/listinfo/asterisk-dev
