From e421f0bcb779e8d5e5f3263c6e48dcb2e0861fb1 Mon Sep 17 00:00:00 2001
From: Tomas Kopecek <tkopecek@redhat.com>
Date: Mon, 3 Apr 2023 13:36:05 +0200
Subject: [PATCH] doc: More XMLRPC-related docs

Related: https://pagure.io/koji/issue/1109
---
 docs/source/using_the_koji_build_system.rst | 38 +++++++++++++++++++++
 www/kojiweb/api.chtml                       |  2 ++
 2 files changed, 40 insertions(+)

diff --git a/docs/source/using_the_koji_build_system.rst b/docs/source/using_the_koji_build_system.rst
index c46815be..e4f022d5 100644
--- a/docs/source/using_the_koji_build_system.rst
+++ b/docs/source/using_the_koji_build_system.rst
@@ -644,3 +644,41 @@ to the xmlrpc standard:
       from Apache's `ws-xmlrpc <https://ws.apache.org/xmlrpc/types.html>`
       implementation. Python's own xmlrpc library understands this tag, even
       thought it will not emit it.
+    * For encoding python-like optional arguments (``**kwargs``) we introduced
+      dictionary in xmlrpc request called ``__starstar``. It is marked by
+      member boolean variable ``__starstar = True``.
+
+So, full example of XML document for hypothetical call ``Method("a", token=1,
+null_value=None, large=10**10)`` would look like:
+
+.. code-block:: xml
+
+    <?xml version='1.0'?>
+    <methodCall>
+        <methodName>Method</methodName>
+        <params>
+            <param>
+                <value><string>first_string</string></value>
+            </param>
+            <param>
+                <value><struct>
+                        <member>
+                            <name>token</name>
+                            <value><int>1</int></value>
+                        </member>
+                        <member>
+                            <name>null_value</name>
+                            <value><nil/></value>
+                        </member>
+                        <member>
+                            <name>large</name>
+                            <value><i8>10000000000</i8></value>
+                        </member>
+                        <member>
+                            <name>__starstar</name>
+                            <value><boolean>1</boolean></value>
+                        </member>
+                </struct></value>
+            </param>
+        </params>
+    </methodCall>
diff --git a/www/kojiweb/api.chtml b/www/kojiweb/api.chtml
index ea2fb3c8..6e871926 100644
--- a/www/kojiweb/api.chtml
+++ b/www/kojiweb/api.chtml
@@ -6,6 +6,8 @@
 Various constants used in API calls can be found in first part of <a
 href="https://pagure.io/koji/blob/master/f/koji/__init__.py">koji module</a>.
 Exceptions which can be raised in python client are just after constants section.
+More details about XMLRPC interface are documented
+<a href="https://docs.pagure.org/koji/using_the_koji_build_system/#koji-xmlrpc-api">here</a>.
 
 Basic anonymous client in python would look like this: