Summary: | ASTERISK-15949: [branch] Appdoc for manager events | ||
Reporter: | Fredrik Liljegren (fiddur) | Labels: | |
Date Opened: | 2010-04-13 01:52:58 | Date Closed: | 2012-09-05 09:22:53 |
Priority: | Major | Regression? | No |
Status: | Closed/Complete | Components: | 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 |