app_amd: Correct documentation to reflect functionality

Update documentation to reflect that maximum_number_of_words
has functionality inconsistent with the variable name (and inconsistent
with prior documentation.)

Update documentation for silence_threshold, which previously implied
that it was measuring time, rather than noise averages in the sample.

Update the comments in amd.conf.sample.

ASTERISK-25639 #close
Change-Id: I4b1451e5dc9cb3cb06d59b6ab872f5275ba79093

apps/app_amd.c

@@ -62,19 +62,19 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 		<syntax>
 			<parameter name="initialSilence" required="false">
 				<para>Is maximum initial silence duration before greeting.</para>
-				<para>If this is exceeded set as MACHINE</para>
+				<para>If this is exceeded, the result is detection as a MACHINE</para>
 			</parameter>
 			<parameter name="greeting" required="false">
 				<para>is the maximum length of a greeting.</para>
-				<para>If this is exceeded set as MACHINE</para>
+				<para>If this is exceeded, the result is detection as a MACHINE</para>
 			</parameter>
 			<parameter name="afterGreetingSilence" required="false">
 				<para>Is the silence after detecting a greeting.</para>
-				<para>If this is exceeded set as HUMAN</para>
+				<para>If this is exceeded, the result is detection as a HUMAN</para>
 			</parameter>
 			<parameter name="totalAnalysis Time" required="false">
 				<para>Is the maximum time allowed for the algorithm</para>
-				<para>to decide HUMAN or MACHINE</para>
+				<para>to decide on whether the audio represents a HUMAN, or a MACHINE</para>
 			</parameter>
 			<parameter name="miniumWordLength" required="false">
 				<para>Is the minimum duration of Voice considered to be a word</para>
@@ -85,14 +85,14 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 			</parameter>
 			<parameter name="maximumNumberOfWords" required="false">
 				<para>Is the maximum number of words in a greeting</para>
-				<para>If this is exceeded set as MACHINE</para>
+				<para>If this is REACHED, then the result is detection as a MACHINE</para>
 			</parameter>
 			<parameter name="silenceThreshold" required="false">
-				<para>How long do we consider silence</para>
+				<para>What is the average level of noise from 0 to 32767 which if not exceeded, should be considered silence?</para>
 			</parameter>
 			<parameter name="maximumWordLength" required="false">
 				<para>Is the maximum duration of a word to accept.</para>
-				<para>If exceeded set as MACHINE</para>
+				<para>If exceeded, then the result is detection as a MACHINE</para>
 			</parameter>
 		</syntax>
 		<description>
@@ -130,7 +130,7 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 					</value>
 					<value name="MAXWORDS">
 						Word Count - maximum number of words.
-					</value>	
+					</value>
 				</variable>
 			</variablelist>
 		</description>

configs/samples/amd.conf.sample

@@ -3,17 +3,29 @@
 ;
 
 [general]
-initial_silence = 2500		; Maximum silence duration before the greeting.
-				; If exceeded then MACHINE.
-greeting = 1500			; Maximum length of a greeting. If exceeded then MACHINE.
-after_greeting_silence = 800	; Silence after detecting a greeting.
-				; If exceeded then HUMAN
 total_analysis_time = 5000	; Maximum time allowed for the algorithm to decide
-				; on a HUMAN or MACHINE
+				; on whether the audio represents a HUMAN, or a MACHINE
+silence_threshold = 256		; If the average level of noise in a sample does not reach
+				; this value, from a scale of 0 to 32767, then we will consider
+				; it to be silence.
+
+; Greeting ;
+initial_silence = 2500		; Maximum silence duration before the greeting.
+				; If exceeded, then the result is detection as a MACHINE.
+after_greeting_silence = 800	; Silence after detecting a greeting.
+				; If exceeded, then the result is detection as a HUMAN
+greeting = 1500			; Maximum length of a greeting. If exceeded, then the
+				; result is detection as a MACHINE.
+
+; Word detection ;
 min_word_length = 100		; Minimum duration of Voice to considered as a word
+maximum_word_length = 5000  	; Maximum duration of a single Voice utterance allowed.
 between_words_silence = 50	; Minimum duration of silence after a word to consider
 				; the audio what follows as a new word
-maximum_number_of_words = 3	; Maximum number of words in the greeting.
+
-				; If exceeded then MACHINE
+maximum_number_of_words = 3	; Maximum number of words in the greeting
-maximum_word_length = 5000      ; Maximum duration of a single Voice utterance allowed.
+				; If REACHED, then the result is detection as a MACHINE
-silence_threshold = 256
+				; WARNING: Releases prior to January 1 2016 documented
+				; maximum_number_of_words as 'if exceeded, then MACHINE',
+				; which did not reflect the true functionality.  In Asterisk 14,
+				; this functionality will change to reflect the variables' name.