From 31c87d1b85e261a6f4562209cf729a634ed0277d Mon Sep 17 00:00:00 2001
From: George Joseph <gjoseph@sangoma.com>
Date: Sat, 9 Nov 2024 15:34:41 -0700
Subject: [PATCH] func_pjsip_aor/contact: Fix documentation for contact ID

Clarified the use of the contact ID returned from PJSIP_AOR.

Resolves: #990
(cherry picked from commit a04e4f38fe7a61156c9e799df5bb568cf433bf51)
---
 funcs/func_pjsip_aor.c     | 19 +++++++++++++++++++
 funcs/func_pjsip_contact.c | 13 ++++++++++++-
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/funcs/func_pjsip_aor.c b/funcs/func_pjsip_aor.c
index 9ae51ed87b..1d24161517 100644
--- a/funcs/func_pjsip_aor.c
+++ b/funcs/func_pjsip_aor.c
@@ -57,6 +57,22 @@
 				Supported options are those fields on the
 				<replaceable>aor</replaceable> object in
 				<filename>pjsip.conf</filename>.</para>
+				<note><para>
+					When requested with this function, the <literal>contact</literal>
+					parameter will return both permanent and dynamic contacts.
+				</para></note>
+				<note><para>
+					The return value of the <literal>contact</literal> parameter is
+					one or more internal contact IDs separated by commans.
+					To get details about the contact itself, including the URI,
+					call the <literal>PJSIP_CONTACT</literal> dialplan function
+					with the contact ID and the desired contact parameter.
+				</para></note>
+				<para>
+				</para>
+				<para>
+				Available Fields:
+				</para>
 				<enumlist>
 					<configOptionToEnum>
 						<xi:include xpointer="xpointer(/docs/configInfo[@name='res_pjsip']/configFile[@name='pjsip.conf']/configObject[@name='aor']/configOption)"/>
@@ -64,6 +80,9 @@
 				</enumlist>
 			</parameter>
 		</syntax>
+		<see-also>
+			<ref type="function">PJSIP_CONTACT</ref>
+		</see-also>
 	</function>
 ***/
 
diff --git a/funcs/func_pjsip_contact.c b/funcs/func_pjsip_contact.c
index 44272e1a0c..a8981eb521 100644
--- a/funcs/func_pjsip_contact.c
+++ b/funcs/func_pjsip_contact.c
@@ -50,7 +50,15 @@
 		</synopsis>
 		<syntax>
 			<parameter name="name" required="true">
-				<para>The name of the contact to query.</para>
+				<para>
+				Contact names are in the form of "aor_id@@hash" for dynamic contacts
+				created by the registrar and permanent contacts defined
+				in a <literal>contact</literal> parameter in an <literal>aor</literal>
+				object.  You can get the "aor_id@@hash" contact ID by calling the
+				<literal>PJSIP_AOR()</literal> dialplpan function with the AOR name
+				and the <literal>contact</literal> field.  You can then pass the value
+				returned to this function.
+				</para>
 			</parameter>
 			<parameter name="field" required="true">
 				<para>The configuration option for the contact to query for.
@@ -69,6 +77,9 @@
 				</enumlist>
 			</parameter>
 		</syntax>
+		<see-also>
+			<ref type="function">PJSIP_AOR</ref>
+		</see-also>
 	</function>
 ***/