Add AMI event documentation

This patch adds the core changes necessary to support AMI event documentation
in the source files of Asterisk, and adds documentation to those AMI events
defined in the core application modules.  Event documentation is built from
the source by two new python scripts, located in build_tools:
get_documentation.py and post_process_documentation.py.

The get_documentation.py script mirrors the actions of the existing AWK
get_documentation scripts, except that it will scan the entirety of a source
file for Asterisk documentation.  Upon encountering it, if the documentation
happens to be an AMI event, it will attempt to extract information about the
event directly from the manager event macro calls that raise the event.  The
post_process_documentation.py script combines manager event instances that
are the same event but documented in multiple source files.  It generates
the final core-[lang].xml file.

As this process can take longer to complete than a typical 'make all', it
is only performed if a new make target, 'full', is chosen.

Review: https://reviewboard.asterisk.org/r/1967/

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@369346 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 62 insertions, 0 deletions

diff --git a/apps/app_confbridge.c b/apps/app_confbridge.c
index 88c85a165..9b1df3404 100644
--- a/apps/app_confbridge.c
+++ b/apps/app_confbridge.c
@@ -529,16 +529,53 @@ static int conf_start_record(struct conference_bridge *conference_bridge)
 
 static void send_conf_start_event(const char *conf_name)
 {
+	/*** DOCUMENTATION
+		<managerEventInstance>
+			<synopsis>Raised when a conference starts.</synopsis>
+			<syntax>
+				<parameter name="Conference">
+					<para>The name of the Confbridge conference.</para>
+				</parameter>
+			</syntax>
+			<see-also>
+				<ref type="managerEvent">ConfbridgeEnd</ref>
+			</see-also>
+		</managerEventInstance>
+	***/
 	manager_event(EVENT_FLAG_CALL, "ConfbridgeStart", "Conference: %s\r\n", conf_name);
 }
 
 static void send_conf_end_event(const char *conf_name)
 {
+	/*** DOCUMENTATION
+		<managerEventInstance>
+			<synopsis>Raised when a conference ends.</synopsis>
+			<syntax>
+				<xi:include xpointer="xpointer(/docs/managerEvent[@name='ConfbridgeStart']/managerEventInstance/syntax/parameter[@name='Conference'])" />
+			</syntax>
+			<see-also>
+				<ref type="managerEvent">ConfbridgeStart</ref>
+				<ref type="application">ConfBridge</ref>
+			</see-also>
+		</managerEventInstance>
+	***/
 	manager_event(EVENT_FLAG_CALL, "ConfbridgeEnd", "Conference: %s\r\n", conf_name);
 }
 
 static void send_join_event(struct ast_channel *chan, const char *conf_name)
 {
+	/*** DOCUMENTATION
+		<managerEventInstance>
+			<synopsis>Raised when a channel joins a Confbridge conference.</synopsis>
+			<syntax>
+				<xi:include xpointer="xpointer(/docs/managerEvent[@name='ConfbridgeStart']/managerEventInstance/syntax/parameter[@name='Conference'])" />
+			</syntax>
+			<see-also>
+				<ref type="managerEvent">ConfbridgeLeave</ref>
+				<ref type="application">ConfBridge</ref>
+			</see-also>
+		</managerEventInstance>
+	***/
 	ast_manager_event(chan, EVENT_FLAG_CALL, "ConfbridgeJoin",
 		"Channel: %s\r\n"
 		"Uniqueid: %s\r\n"
@@ -555,6 +592,17 @@ static void send_join_event(struct ast_channel *chan, const char *conf_name)
 
 static void send_leave_event(struct ast_channel *chan, const char *conf_name)
 {
+	/*** DOCUMENTATION
+		<managerEventInstance>
+			<synopsis>Raised when a channel leaves a Confbridge conference.</synopsis>
+			<syntax>
+				<xi:include xpointer="xpointer(/docs/managerEvent[@name='ConfbridgeStart']/managerEventInstance/syntax/parameter[@name='Conference'])" />
+			</syntax>
+			<see-also>
+				<ref type="managerEvent">ConfbridgeJoin</ref>
+			</see-also>
+		</managerEventInstance>
+	***/
 	ast_manager_event(chan, EVENT_FLAG_CALL, "ConfbridgeLeave",
 		"Channel: %s\r\n"
 		"Uniqueid: %s\r\n"
@@ -1242,6 +1290,20 @@ static void conf_handle_talker_cb(struct ast_bridge *bridge, struct ast_bridge_c
 	}
 
 	/* notify AMI someone is has either started or stopped talking */
+	/*** DOCUMENTATION
+		<managerEventInstance>
+			<synopsis>Raised when a conference participant has started or stopped talking.</synopsis>
+			<syntax>
+				<xi:include xpointer="xpointer(/docs/managerEvent[@name='ConfbridgeStart']/managerEventInstance/syntax/parameter[@name='Conference'])" />
+				<parameter name="TalkingStatus">
+					<enumlist>
+						<enum name="on"/>
+						<enum name="off"/>
+					</enumlist>
+				</parameter>
+			</syntax>
+		</managerEventInstance>
+	***/
 	ast_manager_event(bridge_channel->chan, EVENT_FLAG_CALL, "ConfbridgeTalking",
 	      "Channel: %s\r\n"
 	      "Uniqueid: %s\r\n"