Summary:ASTERISK-15949: [branch] Appdoc for manager events
Reporter:Fredrik Liljegren (fiddur)Labels:
Date Opened:2010-04-13 01:52:58Date Closed:2012-09-05 09:22:53
Versions:Frequency of
Environment:Attachments:( 0) 257023.diff

I recently added a manager event, and wanted to document it, only to
find (or rather NOT find) there's no documentation praxis for manager

I propose adding an appdoc element type for events.

Something like:

 <!ELEMENT ami_event (synopsis?,description?,see-also?)>
 <!ATTLIST ami_event name CDATA #REQUIRED>
 <!ATTLIST ami_event class CDATA #REQUIRED>
 <!ATTLIST ami_event language CDATA #REQUIRED>


<ami_event name="MusicOnHold" class="CALL" language="en_US">
   Occurs when a channel is placed on hold/unhold and music is played
to the caller.
   <para>Triggered when music on hold starts or stops on a channel.</para>
     <variable name="Channel">
       <para>Channel ID</para>
     <variable name="State">
       <value name="Start" />
       <value name="Stop" />
     <variable name="Uniqueid">
       <para>Unique ID</para>
   <ref type="application">MusicOnHold</ref>


I posted this suggestion on asterisk-dev list a whila ago, but didn't get any comments on format, just a few positive remarks on irc that it would be good to have the documentation for events.

Branch available here: http://svn.digium.com/svn/asterisk/team/pabelanger/issue17173/
Comments:By: Leif Madsen (lmadsen) 2010-04-13 11:12:33

Pinging you for feedback on this addition.

By: Eliel Sardanons (eliel) 2010-04-13 11:22:27

We will need the code changes to support this "main_event" and a CLI command to show the documentation.

By: Fredrik Liljegren (fiddur) 2010-04-14 02:32:57

If you think that this is a good idea, I could have a look at making these changes...  I'll need some pointers to what files I am to mess with though :)

By: Eliel Sardanons (eliel) 2010-04-14 08:09:25

you have in main/xmldoc.c all the source code that supports the xml documentation.

You will need to add in xmldoc.c all the functions to support this new kind of documentation.

Add a CLI command like:
        "manager show event <event name>"  and "manager show events"  to show the documentation.

By: Leif Madsen (lmadsen) 2010-04-15 12:27:24

Marking as Confirmed as there is a patch, but more work is necessary to move this to Ready for Testing.

By: Paul Belanger (pabelanger) 2010-04-24 12:48:12

I've been playing around with this issue the last few day:

By: Paul Belanger (pabelanger) 2010-04-24 17:29:09

What do you think of the follow XML elements?
<manager type="Command"...
<manager type="Event"...
or do we want to keep them seperate?

By: Fredrik Liljegren (fiddur) 2010-04-25 12:17:17

Using 'type' attribute corresponds well with the cli commands, they both being 'manager show ...', but it's a different syntax from all else in appdocs, I think...

By: Paul Belanger (pabelanger) 2010-04-25 15:56:40

Include reviewboard link.

I decided to follow the OP suggestion for naming manager elements.

<ami_command> (replacing <manager>)

By: Matt Jordan (mjordan) 2012-09-05 09:22:53.658-0500

Manager Event documentation has been added to Asterisk 11.  A slightly different schema for manager events was used than what is proposed on this issue here.  For more information, please see: