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

Paul Belanger reviewboard at asterisk.org
Wed Jun 6 19:05:55 CDT 2012 

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


Let me be the first to say, THANK YOU! This is an awesome patch for end users.  I'll be scheduling some time tomorrow to test.  A few comments in line, a side from that I am not a fan of having the xmldoc all over the source code, I'd prefer to see it at the top with the other documentation.  I understand it adds new functionality, but that just my opinion.

Thanks again, great work.


./trunk/Makefile
<https://reviewboard.asterisk.org/r/1967/#comment11984>

    Why even have 'make full' and not just do it by default?
    
    Seems weird to me to have 2 different switches for documentation.
    
    Also, wouldn't 'make docs' be appropriate?



./trunk/apps/app_chanspy.c
<https://reviewboard.asterisk.org/r/1967/#comment11982>

    Why managerEventInstance and not just managerEvent? Curious.



./trunk/build_tools/make_version
<https://reviewboard.asterisk.org/r/1967/#comment11980>

    bad merge?



./trunk/build_tools/post_process_documentation.py
<https://reviewboard.asterisk.org/r/1967/#comment11983>

    optparse is deprecated in 2.7, we should change this to argparse if possible.
    
    http://docs.python.org/library/optparse.html


- Paul


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/20120607/0cf5e23c/attachment-0001.htm>

More information about the asterisk-dev mailing list