Add some additional documentation for core AMI events

This patch adds some basic documentation for a number of modules.  This
includes core source files in Asterisk (those in main), as well as
chan_agent, chan_dahdi, chan_local, sig_analog, and sig_pri.  The DTD
has also been updated to allow referencing of AMI commands.

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

5 files changed, 119 insertions, 0 deletions

diff --git a/channels/chan_agent.c b/channels/chan_agent.c
index 2468b091e..888f06831 100644
--- a/channels/chan_agent.c
+++ b/channels/chan_agent.c
@@ -2133,6 +2133,20 @@ static int login_exec(struct ast_channel *chan, const char *data)
 							!ast_strlen_zero(p->moh) ? strlen(p->moh) + 1 : 0);
 						if (p->loginstart == 0)
 							time(&p->loginstart);
+						/*** DOCUMENTATION
+							<managerEventInstance>
+								<synopsis>Raised when an Agent has logged in.</synopsis>
+								<syntax>
+									<parameter name="Agent">
+										<para>The name of the agent.</para>
+									</parameter>
+								</syntax>
+								<see-also>
+									<ref type="application">AgentLogin</ref>
+									<ref type="managerEvent">Agentlogoff</ref>
+								</see-also>
+							</managerEventInstance>
+						***/
 						manager_event(EVENT_FLAG_AGENT, "Agentlogin",
 							      "Agent: %s\r\n"
 							      "Channel: %s\r\n"
@@ -2225,6 +2239,17 @@ static int login_exec(struct ast_channel *chan, const char *data)
 						logintime = time(NULL) - p->loginstart;
 						p->loginstart = 0;
 						ast_mutex_unlock(&p->lock);
+						/*** DOCUMENTATION
+							<managerEventInstance>
+								<synopsis>Raised when an Agent has logged off.</synopsis>
+								<syntax>
+									<xi:include xpointer="xpointer(/docs/managerEvent[@name='Agentlogin']/managerEventInstance/syntax/parameter[@name='Agent'])" />
+								</syntax>
+								<see-also>
+									<ref type="managerEvent">Agentlogin</ref>
+								</see-also>
+							</managerEventInstance>
+						***/
 						manager_event(EVENT_FLAG_AGENT, "Agentlogoff",
 							      "Agent: %s\r\n"
 							      "Logintime: %ld\r\n"
diff --git a/channels/chan_dahdi.c b/channels/chan_dahdi.c
index 59841d1bd..b15caa5be 100644
--- a/channels/chan_dahdi.c
+++ b/channels/chan_dahdi.c
@@ -2175,6 +2175,11 @@ static void dahdi_ami_channel_event(struct dahdi_pvt *p, struct ast_channel *cha
 		/* Real channel */
 		snprintf(ch_name, sizeof(ch_name), "%d", p->channel);
 	}
+	/*** DOCUMENTATION
+		<managerEventInstance>
+			<synopsis>Raised when a DAHDI channel is created or an underlying technology is associated with a DAHDI channel.</synopsis>
+		</managerEventInstance>
+	***/
 	ast_manager_event(chan, EVENT_FLAG_CALL, "DAHDIChannel",
 		"Channel: %s\r\n"
 		"Uniqueid: %s\r\n"
@@ -3866,10 +3871,20 @@ static void handle_clear_alarms(struct dahdi_pvt *p)
 
 	if (report_alarms & REPORT_CHANNEL_ALARMS) {
 		ast_log(LOG_NOTICE, "Alarm cleared on channel %d\n", p->channel);
+		/*** DOCUMENTATION
+			<managerEventInstance>
+				<synopsis>Raised when an alarm is cleared on a DAHDI channel.</synopsis>
+			</managerEventInstance>
+		***/
 		manager_event(EVENT_FLAG_SYSTEM, "AlarmClear", "Channel: %d\r\n", p->channel);
 	}
 	if (report_alarms & REPORT_SPAN_ALARMS && p->manages_span_alarms) {
 		ast_log(LOG_NOTICE, "Alarm cleared on span %d\n", p->span);
+		/*** DOCUMENTATION
+			<managerEventInstance>
+				<synopsis>Raised when an alarm is cleared on a DAHDI span.</synopsis>
+			</managerEventInstance>
+		***/
 		manager_event(EVENT_FLAG_SYSTEM, "SpanAlarmClear", "Span: %d\r\n", p->span);
 	}
 }
@@ -7972,6 +7987,11 @@ static void handle_alarms(struct dahdi_pvt *p, int alms)
 	alarm_str = alarm2str(alms);
 	if (report_alarms & REPORT_CHANNEL_ALARMS) {
 		ast_log(LOG_WARNING, "Detected alarm on channel %d: %s\n", p->channel, alarm_str);
+		/*** DOCUMENTATION
+			<managerEventInstance>
+				<synopsis>Raised when an alarm is set on a DAHDI channel.</synopsis>
+			</managerEventInstance>
+		***/
 		manager_event(EVENT_FLAG_SYSTEM, "Alarm",
 					  "Alarm: %s\r\n"
 					  "Channel: %d\r\n",
@@ -7980,6 +8000,11 @@ static void handle_alarms(struct dahdi_pvt *p, int alms)
 
 	if (report_alarms & REPORT_SPAN_ALARMS && p->manages_span_alarms) {
 		ast_log(LOG_WARNING, "Detected alarm on span %d: %s\n", p->span, alarm_str);
+		/*** DOCUMENTATION
+			<managerEventInstance>
+				<synopsis>Raised when an alarm is set on a DAHDI span.</synopsis>
+			</managerEventInstance>
+		***/
 		manager_event(EVENT_FLAG_SYSTEM, "SpanAlarm",
 					  "Alarm: %s\r\n"
 					  "Span: %d\r\n",
@@ -10027,6 +10052,19 @@ static int dahdi_dnd(struct dahdi_pvt *dahdichan, int flag)
 	ast_verb(3, "%s DND on channel %d\n",
 			flag? "Enabled" : "Disabled",
 			dahdichan->channel);
+	/*** DOCUMENTATION
+		<managerEventInstance>
+			<synopsis>Raised when the Do Not Disturb state is changed on a DAHDI channel.</synopsis>
+			<syntax>
+				<parameter name="Status">
+					<enumlist>
+						<enum name="enabled"/>
+						<enum name="disabled"/>
+					</enumlist>
+				</parameter>
+			</syntax>
+		</managerEventInstance>
+	***/
 	manager_event(EVENT_FLAG_SYSTEM, "DNDState",
 			"Channel: DAHDI/%d\r\n"
 			"Status: %s\r\n", dahdichan->channel,
diff --git a/channels/chan_local.c b/channels/chan_local.c
index 5e72a6153..20e46c9aa 100644
--- a/channels/chan_local.c
+++ b/channels/chan_local.c
@@ -955,6 +955,31 @@ static int local_call(struct ast_channel *ast, const char *dest, int timeout)
 		goto return_cleanup;
 	}
 
+	/*** DOCUMENTATION
+		<managerEventInstance>
+			<synopsis>Raised when two halves of a Local Channel form a bridge.</synopsis>
+			<syntax>
+				<parameter name="Channel1">
+					<para>The name of the Local Channel half that bridges to another channel.</para>
+				</parameter>
+				<parameter name="Channel2">
+					<para>The name of the Local Channel half that executes the dialplan.</para>
+				</parameter>
+				<parameter name="Context">
+					<para>The context in the dialplan that Channel2 starts in.</para>
+				</parameter>
+				<parameter name="Exten">
+					<para>The extension in the dialplan that Channel2 starts in.</para>
+				</parameter>
+				<parameter name="LocalOptimization">
+					<enumlist>
+						<enum name="Yes"/>
+						<enum name="No"/>
+					</enumlist>
+				</parameter>
+			</syntax>
+		</managerEventInstance>
+	***/
 	manager_event(EVENT_FLAG_CALL, "LocalBridge",
 		      "Channel1: %s\r\n"
 		      "Channel2: %s\r\n"
diff --git a/channels/sig_analog.c b/channels/sig_analog.c
index cf51e9727..e84bbc6f8 100644
--- a/channels/sig_analog.c
+++ b/channels/sig_analog.c
@@ -3138,6 +3138,11 @@ static struct ast_frame *__analog_handle_event(struct analog_pvt *p, struct ast_
 	case ANALOG_EVENT_NOALARM:
 		analog_set_alarm(p, 0);
 		ast_log(LOG_NOTICE, "Alarm cleared on channel %d\n", p->channel);
+		/*** DOCUMENTATION
+			<managerEventInstance>
+				<synopsis>Raised when an Alarm is cleared on an Analog channel.</synopsis>
+			</managerEventInstance>
+		***/
 		manager_event(EVENT_FLAG_SYSTEM, "AlarmClear",
 			"Channel: %d\r\n", p->channel);
 		break;
@@ -4013,6 +4018,19 @@ int analog_dnd(struct analog_pvt *p, int flag)
 	ast_verb(3, "%s DND on channel %d\n",
 			flag ? "Enabled" : "Disabled",
 			p->channel);
+	/*** DOCUMENTATION
+		<managerEventInstance>
+			<synopsis>Raised when the Do Not Disturb state is changed on an Analog channel.</synopsis>
+			<syntax>
+				<parameter name="Status">
+					<enumlist>
+						<enum name="enabled"/>
+						<enum name="disabled"/>
+					</enumlist>
+				</parameter>
+			</syntax>
+		</managerEventInstance>
+	***/
 	manager_event(EVENT_FLAG_SYSTEM, "DNDState",
 			"Channel: DAHDI/%d\r\n"
 			"Status: %s\r\n", p->channel,
diff --git a/channels/sig_pri.c b/channels/sig_pri.c
index 31438a945..248999073 100644
--- a/channels/sig_pri.c
+++ b/channels/sig_pri.c
@@ -5153,6 +5153,19 @@ static void sig_pri_moh_fsm_event(struct ast_channel *chan, struct sig_pri_chan
  */
 static void sig_pri_ami_hold_event(struct ast_channel *chan, int is_held)
 {
+	/*** DOCUMENTATION
+		<managerEventInstance>
+			<synopsis>Raised when a PRI channel is put on Hold.</synopsis>
+			<syntax>
+				<parameter name="Status">
+					<enumlist>
+						<enum name="On"/>
+						<enum name="Off"/>
+					</enumlist>
+				</parameter>
+			</syntax>
+		</managerEventInstance>
+	***/
 	ast_manager_event(chan, EVENT_FLAG_CALL, "Hold",
 		"Status: %s\r\n"
 		"Channel: %s\r\n"