[asterisk-dev] [Code Review]: Add AMI event documentation

Matt Jordan reviewboard at asterisk.org
Fri Jun 8 08:30:35 CDT 2012 


> On June 7, 2012, 3:48 p.m., Mark Michelson wrote:
> > ./trunk/include/asterisk/xmldoc.h, line 49
> > <https://reviewboard.asterisk.org/r/1967/diff/1/?file=28584#file28584line49>
> >
> >     I believe that if the doxygen appears above the item in the list, then the < is not necessary. That is only required if you have provided the documentation on the same line as the field.

Fixed


> On June 7, 2012, 3:48 p.m., Mark Michelson wrote:
> > ./trunk/main/manager.c, line 6814
> > <https://reviewboard.asterisk.org/r/1967/diff/1/?file=28585#file28585line6814>
> >
> >     Okay, I'm lost. What is the purpose of this? This seems like an expensive way of accomplishing the same thing as ao2_iterator_init().

In some ways its more expensive (a second allocated container, a malloc'd iterator), and in others, its less expensive.  Since this is an OBJ_MULTIPLE callback, it will create a new container with a reference to each of the items in the original container, with the ref count bumped by one.  This lets you only have to lock the original container during the time it takes to construct the iterator, and not during the actual iteration over the items (and manipulation of them) that were selected during the creation of the iterator.

Admittedly, in this situation, its a bit conservative.  This approach makes a lot of sense for containers that get accessed a lot, as it decreases the time that the item has to be locked.


> On June 7, 2012, 3:48 p.m., Mark Michelson wrote:
> > ./trunk/main/xmldoc.c, lines 1115-1116
> > <https://reviewboard.asterisk.org/r/1967/diff/1/?file=28586#file28586line1115>
> >
> >     Spacing looks odd here. I don't know if it's review board or your changes, though.

Not sure what happened there.  Its all tabs in my editor; I can only assume that Review Board is using something other then 4 spaces for its tabs (or it got off kilter in some fashion).  I'd be fine just removing the tabs in the first place - I only left them in and attempted to align things because that's how the original code had it.


> On June 7, 2012, 3:48 p.m., Mark Michelson wrote:
> > ./trunk/main/manager.c, line 6898
> > <https://reviewboard.asterisk.org/r/1967/diff/1/?file=28585#file28585line6898>
> >
> >     Hm, that "(null)" check there seems odd. Under what circumstance does one of the strings get set to this?

The string is set to (null) when no XML node exists for that particular type, due to a NULL char * being passed to the format specified '%s'.

This is a "bad idea", and those ast_str structs shouldn't be set to anything if no value is returned from the XML documentation construction functions.  Then this hacky check can be replaced with ast_strlen_zero.

Fixed.


> On June 7, 2012, 3:48 p.m., Mark Michelson wrote:
> > ./trunk/main/manager.c, lines 6831-6833
> > <https://reviewboard.asterisk.org/r/1967/diff/1/?file=28585#file28585line6831>
> >
> >     You've got yourself a big ol' ref leak here.

Indeed - fixed.

Ran under valgrind after this - no memory leaks once this was fixed.  Did multiple reloads of manager as well.


- Matt


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


On June 6, 2012, 6:20 p.m., Matt Jordan wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviewboard.asterisk.org/r/1967/
> -----------------------------------------------------------
> 
> (Updated June 6, 2012, 6:20 p.m.)
> 
> 
> Review request for Asterisk Developers, Mark Michelson and wdoekes.
> 
> 
> Summary
> -------
> 
> This patch begins to add AMI event documentation to Asterisk.  This patch includes the following:
> 
> * Pulling AMI event XML documentation out of the Asterisk source and into the XML documentation produced by the build tools
> * Validating the XML when -dev-mode is enabled
> * Reading/parsing the XML documentation when Asterisk starts
> * Two new CLI commands: 'manager show events' and 'manager show event [event_name]'
> * Event documentation for the core applications
> 
> So... AMI events are a bit trickier then other things we've attempted to document in the past.  There were a number of factors to consider when approaching this:
> 1. There are a lot of AMI events, and they are located throughout the code base
> 2. AMI events can occur multiple times with different parameters, but still be the same 'event' type
> 3. AMI events can occur multiple times, in different implementation files
> 4. There is a significant amount of repeated information between events
> 5. Much of the information that a person cares about (AMI event keys) are - more often then not - easily obtained from a method call
> 
> To that end, documentation for AMI events is treated a bit differently then other items.  There are a few major shifts in how the documentation is extracted:
> 1. The previous documentation extraction used an awk script that pulled the documentation from a single comment block (delineated by /*** DOCUMENTATION ... ***/).  That still exists; however, if you want AMI event documentation, you have to use 'make full'.  This calls a different documentation extraction script, written in python.  That script lets us do a few things that the awk script did not:
>  * Documentation can now exist anywhere in the source file
>  * The documentation for manager events can be co-located with the method calls that raise the event.  If the method call is recognized, event parameters are automatically read from the method call and populated in the documentation
>  * Documentation is combined where appropriate.  Thus, if the same event is raised in multiple places, the parameters only need to be defined once.
> 2. Previously, documentation was registered with the application/function/command that it was associated with.  Events are never registered with any controller; requiring them to do so would incur a run-time performance penalty for little gain.  Hence, the xmldoc core now allow documentation for an entire source type to be requested at run-time.  When requested, the documentation is built from the XML read in.
> 
> Example manager events:
> 
> Event: ChanSpyStart
> [Synopsis]
> Raised when a channel has started spying on another channel.
> 
> [Syntax]
> Event: ChanSpyStart
> SpyerChannel: <value>
> SpyeeChannel: <value>
> 
> [See Also]
> ChanSpy(), ExtenSpy(), ChanSpyStop
> 
> -----------------------
> 
> Event: Dial
> [Synopsis]
> Raised when a dial action has started.
> 
> [Syntax]
> Event: Dial
> SubEvent: <value>
> Channel: <value>
> Destination: <value>
> CallerIDNum: <value>
> CallerIDName: <value>
> ConnectedLineNum: <value>
> ConnectedLineName: <value>
> UniqueID: <value>
> DestUniqueID: <value>
> Dialstring: <value>
> 
> [Arguments]
> SubEvent
>     Begin
>     End
>     A sub event type, specifying whether or not the dial action has begun
>     or ended.
> 
> [Synopsis]
> Raised when a dial action has ended.
> 
> [Syntax]
> Event: Dial
> DialStatus: <value>
> SubEvent: <value>
> Channel: <value>
> UniqueID: <value>
> 
> [Arguments]
> DialStatus
>     The value of the ${DIALSTATUS} channel variable.
> SubEvent
>     Begin
>     End
>     A sub event type, specifying whether or not the dial action has begun
>     or ended.
> 
> ---------------------------------
> 
> Event: QueueMemberStatus
> [Synopsis]
> Raised when a Queue member's status has changed.
> 
> [Syntax]
> Event: QueueMemberStatus
> Queue: <value>
> Location: <value>
> MemberName: <value>
> StateInterface: <value>
> Membership: <value>
> Penalty: <value>
> CallsTaken: <value>
> LastCall: <value>
> Status: <value>
> Paused: <value>
> 
> [Arguments]
> Queue
>     The name of the queue.
> Location
>     The queue member's channel technology or location.
> MemberName
>     The name of the queue member.
> StateInterface
>     Channel technology or location from which to read device state
>     changes.
> Membership
>     dynamic
>     realtime
>     static
> Penalty
>     The penalty associated with the queue member.
> CallsTaken
>     The number of calls this queue member has serviced.
> LastCall
>     The time this member last took call, expressed in seconds since 00:00,
>     Jan 1, 1970 UTC.
> Status
>     The status of the queue member.  This will be a device state value.
> Paused
>     0
>     1
> 
> 
> Diffs
> -----
> 
>   ./trunk/apps/app_chanspy.c 367982 
>   ./trunk/apps/app_confbridge.c 367982 
>   ./trunk/apps/app_dial.c 367982 
>   ./trunk/apps/app_meetme.c 367982 
>   ./trunk/apps/app_queue.c 367982 
>   ./trunk/apps/app_stack.c 367982 
>   ./trunk/apps/app_userevent.c 367982 
>   ./trunk/apps/app_voicemail.c 367982 
>   ./trunk/build_tools/get_documentation.py PRE-CREATION 
>   ./trunk/build_tools/make_version 367982 
>   ./trunk/build_tools/post_process_documentation.py PRE-CREATION 
>   ./configure UNKNOWN 
>   ./trunk/Makefile 367982 
>   ./trunk/configure.ac 367982 
>   ./trunk/doc/appdocsxml.dtd 367982 
>   ./trunk/include/asterisk/xmldoc.h 367982 
>   ./trunk/main/manager.c 367982 
>   ./trunk/main/xmldoc.c 367982 
>   ./trunk/makeopts.in 367982 
> 
> Diff: https://reviewboard.asterisk.org/r/1967/diff
> 
> 
> Testing
> -------
> 
> 
> Thanks,
> 
> Matt
> 
>

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

More information about the asterisk-dev mailing list