From: Matt Jordan <mjordan@digium.com>
Date: Fri, 12 Aug 2016 20:53:52 +0000 (-0500)
Subject: res_agi: Improve documentation
X-Git-Tag: 13.12.0-rc1~132^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f9e734974b3718c20885d8023519f3ab64a9dfe0;p=thirdparty%2Fasterisk.git

res_agi: Improve documentation

* Groups of AGI commands that have similar functionality now reference
  each other, and all reference the AGI application for ease of wiki
  reference.

* The documentation for the AGI application has been improved, in
  particular noting the various AGI types and how they are invoked.

* A warning message has been added to DeadAGI, noting that it is
  deprecated.

Change-Id: I479ccdee8a7393f01b18692c3d4ab7e6bdd1875d
---

diff --git a/res/res_agi.c b/res/res_agi.c
index e3839dd6d5..06df75293c 100644
--- a/res/res_agi.c
+++ b/res/res_agi.c
@@ -22,7 +22,6 @@
  *
  * \author Mark Spencer <markster@digium.com>
  *
- * \todo Convert the rest of the AGI commands over to XML documentation
  */
 
 /*** MODULEINFO
@@ -85,6 +84,7 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		</description>
 		<see-also>
 			<ref type="agi">hangup</ref>
+			<ref type="application">AGI</ref>
 		</see-also>
 	</agi>
 	<agi name="asyncagi break" language="en_US">
@@ -98,6 +98,7 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		</description>
 		<see-also>
 			<ref type="agi">hangup</ref>
+			<ref type="application">AGI</ref>
 		</see-also>
 	</agi>
 	<agi name="channel status" language="en_US">
@@ -138,6 +139,9 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 				</enum>
 			</enumlist>
 		</description>
+		<see-also>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="control stream file" language="en_US">
 		<synopsis>
@@ -188,6 +192,11 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 				</variable>
 			</variablelist>
 		</description>
+		<see-also>
+			<ref type="agi">get option</ref>
+			<ref type="agi">control stream file</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="database del" language="en_US">
 		<synopsis>
@@ -203,6 +212,12 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			<para>Returns <literal>1</literal> if successful, <literal>0</literal>
 			otherwise.</para>
 		</description>
+		<see-also>
+			<ref type="agi">database get</ref>
+			<ref type="agi">database put</ref>
+			<ref type="agi">database deltree</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="database deltree" language="en_US">
 		<synopsis>
@@ -217,6 +232,12 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			within a <replaceable>family</replaceable> in the Asterisk database.</para>
 			<para>Returns <literal>1</literal> if successful, <literal>0</literal> otherwise.</para>
 		</description>
+		<see-also>
+			<ref type="agi">database get</ref>
+			<ref type="agi">database put</ref>
+			<ref type="agi">database del</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="database get" language="en_US">
 		<synopsis>
@@ -234,6 +255,12 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			in parenthesis.</para>
 			<para>Example return code: 200 result=1 (testvariable)</para>
 		</description>
+		<see-also>
+			<ref type="agi">database put</ref>
+			<ref type="agi">database del</ref>
+			<ref type="agi">database deltree</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="database put" language="en_US">
 		<synopsis>
@@ -250,6 +277,12 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			<replaceable>value</replaceable>.</para>
 			<para>Returns <literal>1</literal> if successful, <literal>0</literal> otherwise.</para>
 		</description>
+		<see-also>
+			<ref type="agi">database get</ref>
+			<ref type="agi">database del</ref>
+			<ref type="agi">database deltree</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="exec" language="en_US">
 		<synopsis>
@@ -265,6 +298,9 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			<para>Returns whatever the <replaceable>application</replaceable> returns, or
 			<literal>-2</literal> on failure to find <replaceable>application</replaceable>.</para>
 		</description>
+		<see-also>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="get data" language="en_US">
 		<synopsis>
@@ -279,6 +315,9 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			<para>Stream the given <replaceable>file</replaceable>, and receive DTMF data.</para>
 			<para>Returns the digits received from the channel at the other end.</para>
 		</description>
+		<see-also>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="get full variable" language="en_US">
 		<synopsis>
@@ -295,6 +334,11 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			variables, unlike GET VARIABLE.</para>
 			<para>Example return code: 200 result=1 (testvariable)</para>
 		</description>
+		<see-also>
+			<ref type="agi">get variable</ref>
+			<ref type="agi">set variable</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="get option" language="en_US">
 		<synopsis>
@@ -310,6 +354,8 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		</description>
 		<see-also>
 			<ref type="agi">stream file</ref>
+			<ref type="agi">control stream file</ref>
+			<ref type="application">AGI</ref>
 		</see-also>
 	</agi>
 	<agi name="get variable" language="en_US">
@@ -325,6 +371,11 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			the variable in parentheses.</para>
 			<para>Example return code: 200 result=1 (testvariable)</para>
 		</description>
+		<see-also>
+			<ref type="agi">get full variable</ref>
+			<ref type="agi">set variable</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="hangup" language="en_US">
 		<synopsis>
@@ -337,6 +388,9 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			<para>Hangs up the specified channel. If no channel name is given, hangs
 			up the current channel</para>
 		</description>
+		<see-also>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="noop" language="en_US">
 		<synopsis>
@@ -346,6 +400,9 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		<description>
 			<para>Does nothing.</para>
 		</description>
+		<see-also>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="receive char" language="en_US">
 		<synopsis>
@@ -363,6 +420,10 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			if one is received, or <literal>0</literal> if the channel does not support
 			text reception. Returns <literal>-1</literal> only on error/hangup.</para>
 		</description>
+		<see-also>
+			<ref type="agi">receive text</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="receive text" language="en_US">
 		<synopsis>
@@ -379,6 +440,11 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			do not support the reception of text. Returns <literal>-1</literal> for failure
 			or <literal>1</literal> for success, and the string in parenthesis.</para>
 		</description>
+		<see-also>
+			<ref type="agi">receive char</ref>
+			<ref type="agi">send text</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="record file" language="en_US">
 		<synopsis>
@@ -404,6 +470,9 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			lack of dtmf digits or reaching <replaceable>timeout</replaceable>. <replaceable>silence</replaceable>
 			value must be preceded by <literal>s=</literal> and is also optional.</para>
 		</description>
+		<see-also>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="say alpha" language="en_US">
 		<synopsis>
@@ -419,6 +488,15 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			without a digit being pressed, or the ASCII numerical value of the digit if one
 			was pressed or <literal>-1</literal> on error/hangup.</para>
 		</description>
+		<see-also>
+			<ref type="agi">say digits</ref>
+			<ref type="agi">say number</ref>
+			<ref type="agi">say phonetic</ref>
+			<ref type="agi">say date</ref>
+			<ref type="agi">say time</ref>
+			<ref type="agi">say datetime</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="say digits" language="en_US">
 		<synopsis>
@@ -434,6 +512,15 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			without a digit being pressed, or the ASCII numerical value of the digit if one
 			was pressed or <literal>-1</literal> on error/hangup.</para>
 		</description>
+		<see-also>
+			<ref type="agi">say alpha</ref>
+			<ref type="agi">say number</ref>
+			<ref type="agi">say phonetic</ref>
+			<ref type="agi">say date</ref>
+			<ref type="agi">say time</ref>
+			<ref type="agi">say datetime</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="say number" language="en_US">
 		<synopsis>
@@ -450,6 +537,15 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			completes without a digit being pressed, or the ASCII numerical value of
 			the digit if one was pressed or <literal>-1</literal> on error/hangup.</para>
 		</description>
+		<see-also>
+			<ref type="agi">say alpha</ref>
+			<ref type="agi">say digits</ref>
+			<ref type="agi">say phonetic</ref>
+			<ref type="agi">say date</ref>
+			<ref type="agi">say time</ref>
+			<ref type="agi">say datetime</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="say phonetic" language="en_US">
 		<synopsis>
@@ -465,6 +561,15 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			playback completes without a digit pressed, the ASCII numerical value of the digit
 			if one was pressed, or <literal>-1</literal> on error/hangup.</para>
 		</description>
+		<see-also>
+			<ref type="agi">say alpha</ref>
+			<ref type="agi">say digits</ref>
+			<ref type="agi">say number</ref>
+			<ref type="agi">say date</ref>
+			<ref type="agi">say time</ref>
+			<ref type="agi">say datetime</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="say date" language="en_US">
 		<synopsis>
@@ -483,6 +588,15 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			completes without a digit being pressed, or the ASCII numerical value of the
 			digit if one was pressed or <literal>-1</literal> on error/hangup.</para>
 		</description>
+		<see-also>
+			<ref type="agi">say alpha</ref>
+			<ref type="agi">say digits</ref>
+			<ref type="agi">say number</ref>
+			<ref type="agi">say phonetic</ref>
+			<ref type="agi">say time</ref>
+			<ref type="agi">say datetime</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="say time" language="en_US">
 		<synopsis>
@@ -501,6 +615,15 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			without a digit being pressed, or the ASCII numerical value of the digit if
 			one was pressed or <literal>-1</literal> on error/hangup.</para>
 		</description>
+		<see-also>
+			<ref type="agi">say alpha</ref>
+			<ref type="agi">say digits</ref>
+			<ref type="agi">say number</ref>
+			<ref type="agi">say phonetic</ref>
+			<ref type="agi">say date</ref>
+			<ref type="agi">say datetime</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="say datetime" language="en_US">
 		<synopsis>
@@ -528,6 +651,15 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			completes without a digit being pressed, or the ASCII numerical value of the
 			digit if one was pressed or <literal>-1</literal> on error/hangup.</para>
 		</description>
+		<see-also>
+			<ref type="agi">say alpha</ref>
+			<ref type="agi">say digits</ref>
+			<ref type="agi">say number</ref>
+			<ref type="agi">say phonetic</ref>
+			<ref type="agi">say date</ref>
+			<ref type="agi">say time</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="send image" language="en_US">
 		<synopsis>
@@ -542,6 +674,9 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			the channel does not support image transmission.  Returns <literal>-1</literal>
 			only on error/hangup. Image names should not include extensions.</para>
 		</description>
+		<see-also>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="send text" language="en_US">
 		<synopsis>
@@ -559,6 +694,10 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			channel does not support text transmission. Returns <literal>-1</literal> only
 			on error/hangup.</para>
 		</description>
+		<see-also>
+			<ref type="agi">receive text</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="set autohangup" language="en_US">
 		<synopsis>
@@ -572,6 +711,9 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			seconds in the future. Of course it can be hungup before then as well. Setting to
 			<literal>0</literal> will cause the autohangup feature to be disabled on this channel.</para>
 		</description>
+		<see-also>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="set callerid" language="en_US">
 		<synopsis>
@@ -583,6 +725,9 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		<description>
 			<para>Changes the callerid of the current channel.</para>
 		</description>
+		<see-also>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="set context" language="en_US">
 		<synopsis>
@@ -594,6 +739,11 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		<description>
 			<para>Sets the context for continuation upon exiting the application.</para>
 		</description>
+		<see-also>
+			<ref type="agi">set extension</ref>
+			<ref type="agi">set priority</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="set extension" language="en_US">
 		<synopsis>
@@ -605,6 +755,11 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		<description>
 			<para>Changes the extension for continuation upon exiting the application.</para>
 		</description>
+		<see-also>
+			<ref type="agi">set context</ref>
+			<ref type="agi">set priority</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="set music" language="en_US">
 		<synopsis>
@@ -629,6 +784,9 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			used. This generator will be stopped automatically when playing a file.</para>
 			<para>Always returns <literal>0</literal>.</para>
 		</description>
+		<see-also>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="set priority" language="en_US">
 		<synopsis>
@@ -641,6 +799,11 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			<para>Changes the priority for continuation upon exiting the application.
 			The priority must be a valid priority or label.</para>
 		</description>
+		<see-also>
+			<ref type="agi">set context</ref>
+			<ref type="agi">set extension</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="set variable" language="en_US">
 		<synopsis>
@@ -653,6 +816,11 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		<description>
 			<para>Sets a variable to the current channel.</para>
 		</description>
+		<see-also>
+			<ref type="agi">get variable</ref>
+			<ref type="agi">get full variable</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="stream file" language="en_US">
 		<synopsis>
@@ -690,6 +858,8 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		</description>
 		<see-also>
 			<ref type="agi">control stream file</ref>
+			<ref type="agi">get option</ref>
+			<ref type="application">AGI</ref>
 		</see-also>
 	</agi>
 	<agi name="tdd mode" language="en_US">
@@ -708,6 +878,9 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			<para>Enable/Disable TDD transmission/reception on a channel. Returns <literal>1</literal> if
 			successful, or <literal>0</literal> if channel is not TDD-capable.</para>
 		</description>
+		<see-also>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="verbose" language="en_US">
 		<synopsis>
@@ -722,6 +895,9 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			message system. <replaceable>level</replaceable> is the verbose level (1-4).
 			Always returns <literal>1</literal></para>
 		</description>
+		<see-also>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="wait for digit" language="en_US">
 		<synopsis>
@@ -737,6 +913,9 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			one is received. Use <literal>-1</literal> for the <replaceable>timeout</replaceable> value if
 			you desire the call to block indefinitely.</para>
 		</description>
+		<see-also>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="speech create" language="en_US">
 		<synopsis>
@@ -748,6 +927,16 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		<description>
 			<para>Create a speech object to be used by the other Speech AGI commands.</para>
 		</description>
+		<see-also>
+			<ref type="agi">speech set</ref>
+			<ref type="agi">speech destroy</ref>
+			<ref type="agi">speech load grammar</ref>
+			<ref type="agi">speech unload grammar</ref>
+			<ref type="agi">speech activate grammar</ref>
+			<ref type="agi">speech deactivate grammar</ref>
+			<ref type="agi">speech recognize</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="speech set" language="en_US">
 		<synopsis>
@@ -760,6 +949,16 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		<description>
 			<para>Set an engine-specific setting.</para>
 		</description>
+		<see-also>
+			<ref type="agi">speech create</ref>
+			<ref type="agi">speech destroy</ref>
+			<ref type="agi">speech load grammar</ref>
+			<ref type="agi">speech unload grammar</ref>
+			<ref type="agi">speech activate grammar</ref>
+			<ref type="agi">speech deactivate grammar</ref>
+			<ref type="agi">speech recognize</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="speech destroy" language="en_US">
 		<synopsis>
@@ -772,6 +971,13 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		</description>
 		<see-also>
 			<ref type="agi">speech create</ref>
+			<ref type="agi">speech set</ref>
+			<ref type="agi">speech load grammar</ref>
+			<ref type="agi">speech unload grammar</ref>
+			<ref type="agi">speech activate grammar</ref>
+			<ref type="agi">speech deactivate grammar</ref>
+			<ref type="agi">speech recognize</ref>
+			<ref type="application">AGI</ref>
 		</see-also>
 	</agi>
 	<agi name="speech load grammar" language="en_US">
@@ -785,6 +991,16 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		<description>
 			<para>Loads the specified grammar as the specified name.</para>
 		</description>
+		<see-also>
+			<ref type="agi">speech create</ref>
+			<ref type="agi">speech set</ref>
+			<ref type="agi">speech destroy</ref>
+			<ref type="agi">speech unload grammar</ref>
+			<ref type="agi">speech activate grammar</ref>
+			<ref type="agi">speech deactivate grammar</ref>
+			<ref type="agi">speech recognize</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="speech unload grammar" language="en_US">
 		<synopsis>
@@ -796,6 +1012,16 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		<description>
 			<para>Unloads the specified grammar.</para>
 		</description>
+		<see-also>
+			<ref type="agi">speech create</ref>
+			<ref type="agi">speech set</ref>
+			<ref type="agi">speech destroy</ref>
+			<ref type="agi">speech load grammar</ref>
+			<ref type="agi">speech activate grammar</ref>
+			<ref type="agi">speech deactivate grammar</ref>
+			<ref type="agi">speech recognize</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="speech activate grammar" language="en_US">
 		<synopsis>
@@ -807,6 +1033,16 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		<description>
 			<para>Activates the specified grammar on the speech object.</para>
 		</description>
+		<see-also>
+			<ref type="agi">speech create</ref>
+			<ref type="agi">speech set</ref>
+			<ref type="agi">speech destroy</ref>
+			<ref type="agi">speech load grammar</ref>
+			<ref type="agi">speech unload grammar</ref>
+			<ref type="agi">speech deactivate grammar</ref>
+			<ref type="agi">speech recognize</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="speech deactivate grammar" language="en_US">
 		<synopsis>
@@ -818,6 +1054,16 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		<description>
 			<para>Deactivates the specified grammar on the speech object.</para>
 		</description>
+		<see-also>
+			<ref type="agi">speech create</ref>
+			<ref type="agi">speech set</ref>
+			<ref type="agi">speech destroy</ref>
+			<ref type="agi">speech load grammar</ref>
+			<ref type="agi">speech unload grammar</ref>
+			<ref type="agi">speech activate grammar</ref>
+			<ref type="agi">speech recognize</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<agi name="speech recognize" language="en_US">
 		<synopsis>
@@ -832,14 +1078,27 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			<para>Plays back given <replaceable>prompt</replaceable> while listening for
 			speech and dtmf.</para>
 		</description>
+		<see-also>
+			<ref type="agi">speech create</ref>
+			<ref type="agi">speech set</ref>
+			<ref type="agi">speech destroy</ref>
+			<ref type="agi">speech load grammar</ref>
+			<ref type="agi">speech unload grammar</ref>
+			<ref type="agi">speech activate grammar</ref>
+			<ref type="agi">speech deactivate grammar</ref>
+			<ref type="application">AGI</ref>
+		</see-also>
 	</agi>
 	<application name="AGI" language="en_US">
 		<synopsis>
 			Executes an AGI compliant application.
 		</synopsis>
 		<syntax>
-			<parameter name="command" required="true" />
+			<parameter name="command" required="true">
+				<para>How AGI should be invoked on the channel.</para>
+			</parameter>
 			<parameter name="args">
+				<para>Arguments to pass to the AGI script or server.</para>
 				<argument name="arg1" required="true" />
 				<argument name="arg2" multiple="yes" />
 			</parameter>
@@ -848,21 +1107,72 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			<para>Executes an Asterisk Gateway Interface compliant
 			program on a channel. AGI allows Asterisk to launch external programs written
 			in any language to control a telephony channel, play audio, read DTMF digits,
-			etc. by communicating with the AGI protocol on <emphasis>stdin</emphasis> and
-			<emphasis>stdout</emphasis>. As of <literal>1.6.0</literal>, this channel will
+			etc. by communicating with the AGI protocol.</para>
+			<para>The following variants of AGI exist, and are chosen based on the value
+			passed to <replaceable>command</replaceable>:</para>
+			<enumlist>
+				<enum name="AGI">
+					<para>The classic variant of AGI, this will launch the script
+					specified by <replaceable>command</replaceable> as a new process.
+					Communication with the script occurs on <literal>stdin</literal> and
+					<literal>stdout</literal>. If the full path to the script is not
+					provided, the <directory>astagidir</directory> specified in
+					<filename>asterisk.conf</filename> will be used.
+					</para>
+				</enum>
+				<enum name="FastAGI">
+					<para>Connect Asterisk to a FastAGI server using a TCP connection.
+					The URI to the FastAGI server should be given in the form
+					<literal>[scheme]://host.domain[:port][/script/name]</literal>,
+					where <replaceable>scheme</replaceable> is either <literal>agi</literal>
+					or <literal>hagi</literal>.</para>
+					<para>In the case of <literal>hagi</literal>, an SRV lookup will be
+					performed to try to connect to a list of FastAGI servers. The hostname in
+					the URI must be prefixed with <literal>_agi._tcp</literal>. prior to the DNS resolution. For
+					example, if you specify the URI <literal>hagi://agi.example.com/foo.agi</literal>
+					the DNS query would be for <literal>_agi._tcp.agi.example.com</literal>. You
+					will need to make sure this resolves correctly.</para>
+				</enum>
+				<enum name="AsyncAGI">
+					<para>Use AMI to control the channel in AGI. AGI commands can be invoked
+					using the <literal>AMI</literal> action, with a variety of AGI specific
+					events passed back over the AMI connection. AsyncAGI should be invoked
+					by passing <literal>agi:async</literal> to the <replaceable>command</replaceable>
+					parameter.</para>
+				</enum>
+			</enumlist>
+			<note>
+			<para>As of <literal>1.6.0</literal>, this channel will
 			not stop dialplan execution on hangup inside of this application. Dialplan
 			execution will continue normally, even upon hangup until the AGI application
 			signals a desire to stop (either by exiting or, in the case of a net script, by
-			closing the connection). A locally executed AGI script will receive SIGHUP on
-			hangup from the channel except when using DeadAGI. A fast AGI server will
-			correspondingly receive a HANGUP inline with the command dialog. Both of theses
-			signals may be disabled by setting the <variable>AGISIGHUP</variable> channel
-			variable to <literal>no</literal> before executing the AGI application.
+			closing the connection).</para>
+			<para>A locally executed AGI script will receive <literal>SIGHUP</literal> on
+			hangup from the channel except when using <literal>DeadAGI</literal>
+			(or when the channel is already hungup). A fast AGI server will
+			correspondingly receive a <literal>HANGUP</literal> inline with the command dialog.
+			Both of these signals may be disabled by setting the <variable>AGISIGHUP</variable>
+			channel variable to <literal>no</literal> before executing the AGI application.
 			Alternatively, if you would like the AGI application to exit immediately
 			after a channel hangup is detected, set the <variable>AGIEXITONHANGUP</variable>
 			variable to <literal>yes</literal>.</para>
-			<para>Use the CLI command <literal>agi show commands</literal> to list available agi
-			commands.</para>
+			</note>
+			<example title="AGI invocation examples">
+				; Start the AGI script /tmp/my-cool-script.sh, passing it the contents
+				; of the channel variable FOO
+				same => n,AGI(/tmp/my-cool-script.sh,${FOO})
+
+				; Start the AGI script my-cool-script.sh located in the astagidir
+				; directory, specified in asterisk.conf
+				same => n,AGI(my-cool-script.sh)
+
+				; Connect to the FastAGI server located at 127.0.0.1 and start the script
+				; awesome-script
+				same => n,AGI(agi://127.0.0.1/awesome-script)
+
+				; Start AsyncAGI
+				same => n,AGI(agi:async)
+			</example>
 			<para>This application sets the following channel variable upon completion:</para>
 			<variablelist>
 				<variable name="AGISTATUS">
@@ -876,8 +1186,12 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			</variablelist>
 		</description>
 		<see-also>
+			<ref type="manager">AGI</ref>
+			<ref type="managerEvent">AsyncAGIStart</ref>
+			<ref type="managerEvent">AsyncAGIEnd</ref>
 			<ref type="application">EAGI</ref>
 			<ref type="application">DeadAGI</ref>
+			<ref type="filename">asterisk.conf</ref>
 		</see-also>
 	</application>
 	<application name="EAGI" language="en_US">
@@ -890,8 +1204,10 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		</syntax>
 		<description>
 			<para>Using 'EAGI' provides enhanced AGI, with incoming audio available out of band
-			on file descriptor 3.</para>
-			<xi:include xpointer="xpointer(/docs/application[@name='AGI']/description/para)" />
+			on file descriptor 3. In all other respects, it behaves in the same fashion as
+			AGI. See the documentation for the <literal>AGI</literal> dialplan application for
+			more information on invoking AGI on a channel.</para>
+			<para>This application sets the following channel variable upon completion:</para>
 			<xi:include xpointer="xpointer(/docs/application[@name='AGI']/description/variablelist)" />
 		</description>
 		<see-also>
@@ -908,7 +1224,16 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			<xi:include xpointer="xpointer(/docs/application[@name='AGI']/syntax/parameter[@name='args'])" />
 		</syntax>
 		<description>
-			<xi:include xpointer="xpointer(/docs/application[@name='AGI']/description/para)" />
+			<warning>
+				<para>This application is deprecated and may be removed in a future version
+				of Asterisk. Use the replacement application <literal>AGI</literal> instead
+				of <literal>DeadAGI</literal>.
+				</para>
+			</warning>
+			<para>Execute AGI on a 'dead' or hungup channel. See the documentation for the
+			<literal>AGI</literal> dialplan application for more information on invoking
+			AGI on a channel.</para>
+			<para>This application sets the following channel variable upon completion:</para>
 			<xi:include xpointer="xpointer(/docs/application[@name='AGI']/description/variablelist)" />
 		</description>
 		<see-also>
@@ -936,6 +1261,11 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		<description>
 			<para>Add an AGI command to the execute queue of the channel in Async AGI.</para>
 		</description>
+		<see-also>
+			<ref type="managerEvent">AsyncAGIStart</ref>
+			<ref type="managerEvent">AsyncAGIExec</ref>
+			<ref type="managerEvent">AsyncAGIEnd</ref>
+		</see-also>
 	</manager>
 	<managerEvent language="en_US" name="AsyncAGIStart">
 		<managerEventInstance class="EVENT_FLAG_AGI">
@@ -946,6 +1276,12 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 					<para>URL encoded string read from the AsyncAGI server.</para>
 				</parameter>
 			</syntax>
+			<see-also>
+				<ref type="managerEvent">AsyncAGIEnd</ref>
+				<ref type="managerEvent">AsyncAGIExec</ref>
+				<ref type="application">AGI</ref>
+				<ref type="manager">AGI</ref>
+			</see-also>
 		</managerEventInstance>
 	</managerEvent>
 	<managerEvent language="en_US" name="AsyncAGIEnd">
@@ -954,6 +1290,12 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			<syntax>
 				<channel_snapshot/>
 			</syntax>
+			<see-also>
+				<ref type="managerEvent">AsyncAGIStart</ref>
+				<ref type="managerEvent">AsyncAGIExec</ref>
+				<ref type="application">AGI</ref>
+				<ref type="manager">AGI</ref>
+			</see-also>
 		</managerEventInstance>
 	</managerEvent>
 	<managerEvent language="en_US" name="AsyncAGIExec">
@@ -968,6 +1310,12 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 					<para>URL encoded result string from the executed AGI command.</para>
 				</parameter>
 			</syntax>
+			<see-also>
+				<ref type="managerEvent">AsyncAGIStart</ref>
+				<ref type="managerEvent">AsyncAGIEnd</ref>
+				<ref type="application">AGI</ref>
+				<ref type="manager">AGI</ref>
+			</see-also>
 		</managerEventInstance>
 	</managerEvent>
 	<managerEvent language="en_US" name="AGIExecStart">
@@ -982,6 +1330,10 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 					<para>Random identification number assigned to the execution of this command.</para>
 				</parameter>
 			</syntax>
+			<see-also>
+				<ref type="managerEvent">AGIExecEnd</ref>
+				<ref type="application">AGI</ref>
+			</see-also>
 		</managerEventInstance>
 	</managerEvent>
 	<managerEvent language="en_US" name="AGIExecEnd">
@@ -997,6 +1349,10 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 					<para>The text result reason from AGI</para>
 				</parameter>
 			</syntax>
+			<see-also>
+				<ref type="managerEvent">AGIExecStart</ref>
+				<ref type="application">AGI</ref>
+			</see-also>
 		</managerEventInstance>
 	</managerEvent>
  ***/