From: Ben Ford <bford@digium.com>
Date: Fri, 14 Mar 2025 22:05:30 +0000 (-0500)
Subject: documentation: Update Gosub, Goto, and add new documentationtype.
X-Git-Tag: 21.8.0-rc1~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d9b715a5826c86c221d931038c7ba82f6055fd27;p=thirdparty%2Fasterisk.git

documentation: Update Gosub, Goto, and add new documentationtype.

Gosub and Goto were not displaying their syntax correctly on the docs
site. This change adds a new way to specify an optional context, an
optional extension, and a required priority that the xml stylesheet can
parse without having to know which optional parameters come in which
order. In Asterisk, it looks like this:

  parameter name="context" documentationtype="dialplan_context"
  parameter name="extension" documentationtype="dialplan_extension"
  parameter name="priority" documentationtype="dialplan_priority" required="true"

The stylesheet will ignore the context and extension parameters, but for
priority, it will automatically inject the following:

  [[context,]extension,]priority

This is the correct oder for applications such as Gosub and Goto.

(cherry picked from commit 6921ede7cbcd68046e9f3efe3085ef53f1573fa0)
---

diff --git a/apps/app_stack.c b/apps/app_stack.c
index 26fc2c4bb9..187ef7de44 100644
--- a/apps/app_stack.c
+++ b/apps/app_stack.c
@@ -49,9 +49,9 @@
 			Jump to label, saving return address.
 		</synopsis>
 		<syntax>
-			<parameter name="context" />
-			<parameter name="exten" />
-			<parameter name="priority" required="true" hasparams="optional">
+			<parameter name="context" documentationtype="dialplan_context" />
+			<parameter name="extension" documentationtype="dialplan_extension" />
+			<parameter name="priority" documentationtype="dialplan_priority" required="true" hasparams="optional">
 				<argument name="arg1" multiple="true" required="true" />
 				<argument name="argN" />
 			</parameter>
diff --git a/doc/appdocsxml.dtd b/doc/appdocsxml.dtd
index ad5f16c0b6..85763ff24f 100644
--- a/doc/appdocsxml.dtd
+++ b/doc/appdocsxml.dtd
@@ -122,7 +122,7 @@
 
   <!ELEMENT description (para|note|warning|variablelist|enumlist|info|example|xi:include)*>
 
-  <!ELEMENT parameter (optionlist|enumlist|argument|para|note|warning|parameter|info|xi:include)*>
+  <!ELEMENT parameter (optionlist|enumlist|argument|para|note|warning|parameter|info|documentationtype|xi:include)*>
   <!ATTLIST parameter name CDATA "">
   <!ATTLIST parameter required (yes|no|true|false) "false">
   <!ATTLIST parameter multiple (yes|no|true|false) "false">
@@ -130,6 +130,7 @@
   <!ATTLIST parameter literal (yes|no|true|false) "false">
   <!ATTLIST parameter default CDATA "">
   <!ATTLIST parameter argsep CDATA ",">
+  <!ATTLIST parameter documentationtype CDATA "">
 
   <!ELEMENT optionlist (option+)>
   <!ELEMENT option (argument|para|note|warning|variablelist|enumlist|info|xi:include)*>
diff --git a/main/pbx_builtins.c b/main/pbx_builtins.c
index 972e4b1957..859f939921 100644
--- a/main/pbx_builtins.c
+++ b/main/pbx_builtins.c
@@ -227,9 +227,9 @@
 			Jump to a particular priority, extension, or context.
 		</synopsis>
 		<syntax>
-			<parameter name="context" />
-			<parameter name="extensions" />
-			<parameter name="priority" required="true" />
+			<parameter name="context" documentationtype="dialplan_context" />
+			<parameter name="extension" documentationtype="dialplan_extension" />
+			<parameter name="priority" documentationtype="dialplan_priority" required="true" />
 		</syntax>
 		<description>
 			<para>This application will set the current context, extension, and priority in the channel structure.