[Home]

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
Priority:MajorRegression?No
Status:Closed/CompleteComponents:Core/NewFeature
Versions:Frequency of
Occurrence
Related
Issues:
Environment:Attachments:( 0) 257023.diff
Description:Hi.

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
events.

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>

Example:

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



****** ADDITIONAL INFORMATION ******

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:
http://svn.digium.com/svn/asterisk/team/pabelanger/issue17173/
By: Paul Belanger (pabelanger) 2010-04-24 17:29:09

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


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>)
<ami_event>
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:

https://wiki.asterisk.org/wiki/display/AST/AMI+Event+Documentation