res_parking: Update parking documentation for dynamic parking lots.

* Remove duplicate res_parking.conf courtesytone config option
documentation.

ASTERISK-24596 #close
Reported by:  Philip Correia

ASTERISK-24605
Reported by:  Philip Correia
Patches:
      call_park_app_doc.patch (license #6672) patch uploaded by Philip Correia

Change-Id: I90a92a891c6494dc08173e675856afcc4764c5b5

2 files changed, 96 insertions, 10 deletions

diff --git a/res/parking/parking_applications.c b/res/parking/parking_applications.c
index d8cda6f50..fdd15ae43 100644
--- a/res/parking/parking_applications.c
+++ b/res/parking/parking_applications.c
@@ -90,6 +90,47 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 				call on that extension. If the extension is already in use then execution
 				will continue at the next priority.
 			</para>
+			<para>If the <literal>parkeddynamic</literal> option is enabled in
+				<filename>res_parking.conf</filename> the following variables can be
+				used to dynamically create new parking lots. When using dynamic parking
+				lots, be aware of the conditions as explained in the notes section
+				below.
+			</para>
+			<para>The <variable>PARKINGDYNAMIC</variable> variable specifies the
+				parking lot to use as a template to create a dynamic parking lot. It
+				is an error to specify a non-existent parking lot for the template.
+				If not set then the default parking lot is used as the template.
+			</para>
+			<para>The <variable>PARKINGDYNCONTEXT</variable> variable specifies the
+				dialplan context to use for the newly created dynamic parking lot. If
+				not set then the context from the parking lot template is used. The
+				context is created if it does not already exist and the new parking lot
+				needs to create extensions.
+			</para>
+			<para>The <variable>PARKINGDYNEXTEN</variable> variable specifies the
+				<literal>parkext</literal> to use for the newly created dynamic
+				parking lot. If not set then the <literal>parkext</literal> is used from
+				the parking lot template. If the template does not specify a
+				<literal>parkext</literal> then no extensions are created for the newly
+				created parking lot. The dynamic parking lot cannot be created if it
+				needs to create extensions that overlap existing parking lot extensions.
+				The only exception to this is for the <literal>parkext</literal>
+				extension and only if neither of the overlaping parking lot's
+				<literal>parkext</literal> is exclusive.
+			</para>
+			<para>The <variable>PARKINGDYNPOS</variable> variable specifies the
+				parking positions to use for the newly created dynamic parking lot. If
+				not set then the <literal>parkpos</literal> from the parking lot template
+				is used.
+			</para>
+			<note>
+				<para>This application must be used as the first extension priority
+					to be recognized as a parking access extension for blind transfers.
+					Blind transfers and the DTMF one-touch parking feature need this
+					distinction to operate properly. The parking access extension in
+					this case is treated like a dialplan hint.
+				</para>
+			</note>
 		</description>
 		<see-also>
 			<ref type="application">ParkedCall</ref>
diff --git a/res/res_parking.c b/res/res_parking.c
index 3edbd4663..0a9e6d1a3 100644
--- a/res/res_parking.c
+++ b/res/res_parking.c
@@ -35,6 +35,38 @@
 				<synopsis>Options that apply to every parking lot</synopsis>
 				<configOption name="parkeddynamic">
 					<synopsis>Enables dynamically created parkinglots.</synopsis>
+					<description>
+						<para>If the option is enabled then the following variables can
+							be used to dynamically create new parking lots.
+						</para>
+						<para>The <variable>PARKINGDYNAMIC</variable> variable specifies the
+							parking lot to use as a template to create a dynamic parking lot. It
+							is an error to specify a non-existent parking lot for the template.
+							If not set then the default parking lot is used as the template.
+						</para>
+						<para>The <variable>PARKINGDYNCONTEXT</variable> variable specifies the
+							dialplan context to use for the newly created dynamic parking lot. If
+							not set then the context from the parking lot template is used. The
+							context is created if it does not already exist and the new parking lot
+							needs to create extensions.
+						</para>
+						<para>The <variable>PARKINGDYNEXTEN</variable> variable specifies the
+							<literal>parkext</literal> to use for the newly created dynamic
+							parking lot. If not set then the <literal>parkext</literal> is used from
+							the parking lot template. If the template does not specify a
+							<literal>parkext</literal> then no extensions are created for the newly
+							created parking lot. The dynamic parking lot cannot be created if it
+							needs to create extensions that overlap existing parking lot extensions.
+							The only exception to this is for the <literal>parkext</literal>
+							extension and only if neither of the overlaping parking lot's
+							<literal>parkext</literal> is exclusive.
+						</para>
+						<para>The <variable>PARKINGDYNPOS</variable> variable specifies the
+							parking positions to use for the newly created dynamic parking lot. If
+							not set then the <literal>parkpos</literal> from the parking lot template
+							is used.
+						</para>
+					</description>
 				</configOption>
 			</configObject>
 			<configObject name="parking_lot">
@@ -45,19 +77,35 @@
 				</configOption>
 				<configOption name="parkext">
 					<synopsis>Extension to park calls to this parking lot.</synopsis>
-					<description><para>If this option is used, this extension will automatically be created to place calls into
-                        parking lots. In addition, if parkext_exclusive is set for this parking lot, the name of the parking lot
-                        will be included in the application's arguments so that it only parks to this parking lot. The extension
-                        will be created in <literal>context</literal>. Using this option also creates extensions for retrieving
-                        parked calls from the parking spaces in the same context.</para></description>
+					<description>
+						<para>If this option is used, this extension will automatically
+							be created to place calls into parking lots. In addition, if
+							<literal>parkext_exclusive</literal> is set for this parking
+							lot, the name of the parking lot will be included in the
+							application's arguments so that it only parks to this parking
+							lot. The extension will be created in <literal>context</literal>.
+							Using this option also creates extensions for retrieving
+							parked calls from the parking spaces in the same context.
+						</para>
+						<note>
+							<para>Generated parking extensions cannot overlap.
+								The only exception is if neither overlapping
+								<literal>parkext</literal> is exclusive.
+							</para>
+						</note>
+					</description>
 				</configOption>
 				<configOption name="parkext_exclusive" default="no">
 					<synopsis>If yes, the extension registered as parkext will park exclusively to this parking lot.</synopsis>
 				</configOption>
 				<configOption name="parkpos" default="701-750">
 					<synopsis>Numerical range of parking spaces which can be used to retrieve parked calls.</synopsis>
-					<description><para>If parkext is set, these extensions will automatically be mapped in <literal>context</literal>
-						in order to pick up calls parked to these parking spaces.</para></description>
+					<description>
+						<para>If <literal>parkext</literal> is set, these extensions
+							will automatically be mapped in <literal>context</literal>
+							in order to pick up calls parked to these parking spaces.
+						</para>
+					</description>
 				</configOption>
 				<configOption name="parkinghints" default="no">
 					<synopsis>If yes, this parking lot will add hints automatically for parking spaces.</synopsis>
@@ -178,9 +226,6 @@
 						</enumlist>
 					</description>
 				</configOption>
-				<configOption name="courtesytone">
-					<synopsis>If set, the sound set will be played to whomever is set by parkedplay</synopsis>
-				</configOption>
 			</configObject>
 		</configFile>
 	</configInfo>