Move Speech* applications and functions documentation to XML.

git-svn-id: http://svn.digium.com/svn/asterisk/trunk@161536 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 216 insertions, 92 deletions

diff --git a/apps/app_speech_utils.c b/apps/app_speech_utils.c
index 1b8348a04..670efa2bf 100644
--- a/apps/app_speech_utils.c
+++ b/apps/app_speech_utils.c
@@ -37,62 +37,213 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$");
 #include "asterisk/app.h"
 #include "asterisk/speech.h"
 
-/* Descriptions for each application */
-static char *speechcreate_descrip =
-"  SpeechCreate(engine name):\n"
-"This application creates information to be used by all the other applications.\n"
-"It must be called before doing any speech recognition activities such as activating a grammar.\n"
-"It takes the engine name to use as the argument, if not specified the default engine will be used.\n";
-
-static char *speechactivategrammar_descrip =
-"  SpeechActivateGrammar(Grammar Name):\n"
-"This activates the specified grammar to be recognized by the engine.\n"
-"A grammar tells the speech recognition engine what to recognize, and how to portray it back to you \n"
-"in the dialplan. The grammar name is the only argument to this application.\n";
-
-static char *speechstart_descrip =
-"  SpeechStart():\n"
-"Tell the speech recognition engine that it should start trying to get results from audio being \n"
-"fed to it. This has no arguments.\n";
-
-static char *speechbackground_descrip =
-"  SpeechBackground(<Sound File>[,Timeout[,options]]):\n"
-"This application plays a sound file and waits for the person to speak. Once they start speaking playback\n"
-"of the file stops, and silence is heard. Once they stop talking the processing sound is played to indicate\n"
-"the speech recognition engine is working. Once results are available the application returns and results \n"
-"(score and text) are available using dialplan functions.\n"
-"  The first text and score are ${SPEECH_TEXT(0)} AND ${SPEECH_SCORE(0)} while the second are ${SPEECH_TEXT(1)}\n"
-"and ${SPEECH_SCORE(1)}.\n"
-"  The first argument is the sound file and the second is the timeout integer in seconds. Note the timeout will\n"
-"only start once the sound file has stopped playing. The third argument specifies options:\n"
-"  Valid Options:\n"
-"    n - Don't answer the channel if it has not already been answered.\n";
-
-static char *speechdeactivategrammar_descrip =
-"  SpeechDeactivateGrammar(Grammar Name):\n"
-"This deactivates the specified grammar so that it is no longer recognized.\n"
-"The only argument is the grammar name to deactivate.\n";
-
-static char *speechprocessingsound_descrip =
-"  SpeechProcessingSound(Sound File):\n"
-"This changes the processing sound that SpeechBackground plays back when the speech recognition engine is\n"
-"processing and working to get results.\n"
-"It takes the sound file as the only argument.\n";
-
-static char *speechdestroy_descrip =
-"  SpeechDestroy():\n"
-"This destroys the information used by all the other speech recognition applications.\n"
-"If you call this application but end up wanting to recognize more speech, you must call SpeechCreate\n"
-	"again before calling any other application. It takes no arguments.\n";
-
-static char *speechload_descrip =
-"  SpeechLoadGrammar(Grammar Name,Path):\n"
-"Load a grammar only on the channel, not globally.\n"
-"It takes the grammar name as first argument and path as second.\n";
-
-static char *speechunload_descrip =
-"  SpeechUnloadGrammar(Grammar Name):\n"
-"Unload a grammar. It takes the grammar name as the only argument.\n";
+/*** DOCUMENTATION
+	<application name="SpeechCreate" language="en_US">
+		<synopsis>
+			Create a Speech Structure.
+		</synopsis>
+		<syntax>
+			<parameter name="engine_name" required="true" />
+		</syntax>
+		<description>
+			<para>This application creates information to be used by all the other applications.
+			It must be called before doing any speech recognition activities such as activating a grammar.
+			It takes the engine name to use as the argument, if not specified the default engine will be used.</para>
+		</description>
+	</application>
+	<application name="SpeechActivateGrammar" language="en_US">
+		<synopsis>
+			Activate a grammar.
+		</synopsis>
+		<syntax>
+			<parameter name="grammar_name" required="true" />
+		</syntax>
+		<description>
+			<para>This activates the specified grammar to be recognized by the engine.
+			A grammar tells the speech recognition engine what to recognize, and how to portray it back to you
+			in the dialplan. The grammar name is the only argument to this application.</para>
+		</description>
+	</application>
+	<application name="SpeechStart" language="en_US">
+		<synopsis>
+			Start recognizing voice in the audio stream.
+		</synopsis>
+		<syntax />
+		<description>
+			<para>Tell the speech recognition engine that it should start trying to get results from audio being
+			fed to it.</para>
+		</description>
+	</application>
+	<application name="SpeechBackground" language="en_US">
+		<synopsis>
+			Play a sound file and wait for speech to be recognized.
+		</synopsis>
+		<syntax>
+			<parameter name="sound_file" required="true" />
+			<parameter name="timeout">
+				<para>Timeout integer in seconds. Note the timeout will only start
+				once the sound file has stopped playing.</para>
+			</parameter>
+			<parameter name="options">
+				<optionlist>
+					<option name="n">
+						<para>Don't answer the channel if it has not already been answered.</para>
+					</option>
+				</optionlist>
+			</parameter>
+		</syntax>
+		<description>
+			<para>This application plays a sound file and waits for the person to speak. Once they start speaking playback
+			of the file stops, and silence is heard. Once they stop talking the processing sound is played to indicate
+			the speech recognition engine is working. Once results are available the application returns and results
+			(score and text) are available using dialplan functions.</para>
+			<para>The first text and score are ${SPEECH_TEXT(0)} AND ${SPEECH_SCORE(0)} while the second are ${SPEECH_TEXT(1)}
+			and ${SPEECH_SCORE(1)}.</para>
+			<para>The first argument is the sound file and the second is the timeout integer in seconds.</para>
+			
+		</description>
+	</application>
+	<application name="SpeechDeactivateGrammar" language="en_US">
+		<synopsis>
+			Deactivate a grammar.
+		</synopsis>
+		<syntax>
+			<parameter name="grammar_name" required="true">
+				<para>The grammar name to deactivate</para>
+			</parameter>
+		</syntax>
+		<description>
+			<para>This deactivates the specified grammar so that it is no longer recognized.</para>
+		</description>
+	</application>
+	<application name="SpeechProcessingSound" language="en_US">
+		<synopsis>
+			Change background processing sound.
+		</synopsis>
+		<syntax>
+			<parameter name="sound_file" required="true" />
+		</syntax>
+		<description>
+			<para>This changes the processing sound that SpeechBackground plays back when the speech recognition engine is
+			processing and working to get results.</para>
+		</description>
+	</application>
+	<application name="SpeechDestroy" language="en_US">
+		<synopsis>
+			End speech recognition.
+		</synopsis>
+		<syntax />
+		<description>
+			<para>This destroys the information used by all the other speech recognition applications.
+			If you call this application but end up wanting to recognize more speech, you must call SpeechCreate()
+			again before calling any other application.</para>
+		</description>
+	</application>
+	<application name="SpeechLoadGrammar" language="en_US">
+		<synopsis>
+			Load a grammar.
+		</synopsis>
+		<syntax>
+			<parameter name="grammar_name" required="true" />
+			<parameter name="path" required="true" />
+		</syntax>
+		<description>
+			<para>Load a grammar only on the channel, not globally.</para>
+		</description>
+	</application>
+	<application name="SpeechUnloadGrammar" language="en_US">
+		<synopsis>
+			Unload a grammar.
+		</synopsis>
+		<syntax>
+			<parameter name="grammar_name" required="true" />
+		</syntax>
+		<description>
+			<para>Unload a grammar.</para>
+		</description>
+	</application>
+	<function name="SPEECH_SCORE" language="en_US">
+		<synopsis>
+			Gets the confidence score of a result.
+		</synopsis>
+		<syntax argsep="/">
+			<parameter name="nbest_number" />
+			<parameter name="result_number" required="true" />
+		</syntax>
+		<description>
+			<para>Gets the confidence score of a result.</para>
+		</description>
+	</function>
+	<function name="SPEECH_TEXT" language="en_US">
+		<synopsis>
+			Gets the recognized text of a result.
+		</synopsis>
+		<syntax argsep="/">
+			<parameter name="nbest_number" />
+			<parameter name="result_number" required="true" />
+		</syntax>
+		<description>
+			<para>Gets the recognized text of a result.</para>
+		</description>
+	</function>
+	<function name="SPEECH_GRAMMAR" language="en_US">
+		<synopsis>
+			Gets the matched grammar of a result if available.
+		</synopsis>
+		<syntax argsep="/">
+			<parameter name="nbest_number" />
+			<parameter name="result_number" required="true" />
+		</syntax>
+		<description>
+			<para>Gets the matched grammar of a result if available.</para>
+		</description>
+	</function>
+	<function name="SPEECH_ENGINE" language="en_US">
+		<synopsis>
+			Change a speech engine specific attribute.
+		</synopsis>
+		<syntax>
+			<parameter name="name" required="true" />
+		</syntax>
+		<description>
+			<para>Changes a speech engine specific attribute.</para>
+		</description>
+	</function>
+	<function name="SPEECH_RESULTS_TYPE" language="en_US">
+		<synopsis>
+			Sets the type of results that will be returned.
+		</synopsis>
+		<syntax />
+		<description>
+			<para>Sets the type of results that will be returned. Valid options are normal or nbest.</para>
+		</description>
+	</function>
+	<function name="SPEECH" language="en_US">
+		<synopsis>
+			Gets information about speech recognition results.
+		</synopsis>
+		<syntax>
+			<parameter name="argument" required="true">
+				<enumlist>
+					<enum name="status">
+						<para>Returns <literal>1</literal> upon speech object existing,
+						or <literal>0</literal> if not</para>
+					</enum>
+					<enum name="spoke">
+						<para>Returns <literal>1</literal> if spoker spoke,
+						or <literal>0</literal> if not</para>
+					</enum>
+					<enum name="results">
+						<para>Returns number of results that were recognized.</para>
+					</enum>
+				</enumlist>
+			</parameter>
+		</syntax>
+		<description>
+			<para>Gets information about speech recognition results.</para>
+		</description>
+	</function>
+ ***/
 
 /*! \brief Helper function used by datastores to destroy the speech structure upon hangup */
 static void destroy_callback(void *data)
@@ -181,10 +332,6 @@ static int speech_score(struct ast_channel *chan, const char *cmd, char *data,
 
 static struct ast_custom_function speech_score_function = {
 	.name = "SPEECH_SCORE",
-	.synopsis = "Gets the confidence score of a result.",
-	.syntax = "SPEECH_SCORE([nbest number/]result number)",
-	.desc =
-	"Gets the confidence score of a result.\n",
 	.read = speech_score,
 	.write = NULL,
 };
@@ -211,10 +358,6 @@ static int speech_text(struct ast_channel *chan, const char *cmd, char *data,
 
 static struct ast_custom_function speech_text_function = {
 	.name = "SPEECH_TEXT",
-	.synopsis = "Gets the recognized text of a result.",
-	.syntax = "SPEECH_TEXT([nbest number/]result number)",
-	.desc =
-	"Gets the recognized text of a result.\n",
 	.read = speech_text,
 	.write = NULL,
 };
@@ -241,10 +384,6 @@ static int speech_grammar(struct ast_channel *chan, const char *cmd, char *data,
 
 static struct ast_custom_function speech_grammar_function = {
 	.name = "SPEECH_GRAMMAR",
-	.synopsis = "Gets the matched grammar of a result if available.",
-	.syntax = "SPEECH_GRAMMAR([nbest number/]result number)",
-	.desc =
-	"Gets the matched grammar of a result if available.\n",
 	.read = speech_grammar,
 	.write = NULL,
 };
@@ -265,10 +404,6 @@ static int speech_engine_write(struct ast_channel *chan, const char *cmd, char *
 
 static struct ast_custom_function speech_engine_function = {
 	.name = "SPEECH_ENGINE",
-	.synopsis = "Change a speech engine specific attribute.",
-	.syntax = "SPEECH_ENGINE(name)=value",
-	.desc =
-	"Changes a speech engine specific attribute.\n",
 	.read = NULL,
 	.write = speech_engine_write,
 };
@@ -291,10 +426,6 @@ static int speech_results_type_write(struct ast_channel *chan, const char *cmd,
 
 static struct ast_custom_function speech_results_type_function = {
 	.name = "SPEECH_RESULTS_TYPE",
-	.synopsis = "Sets the type of results that will be returned.",
-	.syntax = "SPEECH_RESULTS_TYPE()=results type",
-	.desc =
-	"Sets the type of results that will be returned. Valid options are normal or nbest.",
 	.read = NULL,
 	.write = speech_results_type_write,
 };
@@ -343,13 +474,6 @@ static int speech_read(struct ast_channel *chan, const char *cmd, char *data,
 
 static struct ast_custom_function speech_function = {
 	.name = "SPEECH",
-	.synopsis = "Gets information about speech recognition results.",
-	.syntax = "SPEECH(argument)",
-	.desc =
-	"Gets information about speech recognition results.\n"
-	"status:   Returns 1 upon speech object existing, or 0 if not\n"
-	"spoke:  Returns 1 if spoker spoke, or 0 if not\n"
-	"results:  Returns number of results that were recognized\n",
 	.read = speech_read,
 	.write = NULL,
 };
@@ -810,15 +934,15 @@ static int load_module(void)
 {
 	int res = 0;
 
-	res = ast_register_application("SpeechCreate", speech_create, "Create a Speech Structure", speechcreate_descrip);
-	res |= ast_register_application("SpeechLoadGrammar", speech_load, "Load a Grammar", speechload_descrip);
-	res |= ast_register_application("SpeechUnloadGrammar", speech_unload, "Unload a Grammar", speechunload_descrip);
-	res |= ast_register_application("SpeechActivateGrammar", speech_activate, "Activate a Grammar", speechactivategrammar_descrip);
-	res |= ast_register_application("SpeechDeactivateGrammar", speech_deactivate, "Deactivate a Grammar", speechdeactivategrammar_descrip);
-	res |= ast_register_application("SpeechStart", speech_start, "Start recognizing voice in the audio stream", speechstart_descrip);
-	res |= ast_register_application("SpeechBackground", speech_background, "Play a sound file and wait for speech to be recognized", speechbackground_descrip);
-	res |= ast_register_application("SpeechDestroy", speech_destroy, "End speech recognition", speechdestroy_descrip);
-	res |= ast_register_application("SpeechProcessingSound", speech_processing_sound, "Change background processing sound", speechprocessingsound_descrip);
+	res = ast_register_application_xml("SpeechCreate", speech_create);
+	res |= ast_register_application_xml("SpeechLoadGrammar", speech_load);
+	res |= ast_register_application_xml("SpeechUnloadGrammar", speech_unload);
+	res |= ast_register_application_xml("SpeechActivateGrammar", speech_activate);
+	res |= ast_register_application_xml("SpeechDeactivateGrammar", speech_deactivate);
+	res |= ast_register_application_xml("SpeechStart", speech_start);
+	res |= ast_register_application_xml("SpeechBackground", speech_background);
+	res |= ast_register_application_xml("SpeechDestroy", speech_destroy);
+	res |= ast_register_application_xml("SpeechProcessingSound", speech_processing_sound);
 	res |= ast_custom_function_register(&speech_function);
 	res |= ast_custom_function_register(&speech_score_function);
 	res |= ast_custom_function_register(&speech_text_function);