From 4960cffcb49ce9b996b820103e48702d694239a1 Mon Sep 17 00:00:00 2001
From: mathieui <mathieui@mathieui.net>
Date: Sun, 14 Feb 2021 11:56:20 +0100
Subject: XEP-0115: API changes

- ``get_verstring``, ``get_caps`` are now coroutines.
- ``assign_verstring``, ``cache_caps`` now return a Future.

side-effect: fix supports() and has_identity() broken since forever
---
 docs/api/plugins/xep_0115.rst | 46 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

(limited to 'docs/api')

diff --git a/docs/api/plugins/xep_0115.rst b/docs/api/plugins/xep_0115.rst
index 73d0e77b..39ea1333 100644
--- a/docs/api/plugins/xep_0115.rst
+++ b/docs/api/plugins/xep_0115.rst
@@ -8,6 +8,52 @@ XEP-0115: Entity Capabilities
     :members:
     :exclude-members: session_bind, plugin_init, plugin_end
 
+Internal API methods
+--------------------
+
+This internal API extends the Disco internal API, and also manages an
+in-memory cache of verstring→disco info, and fulljid→verstring.
+
+.. glossary::
+
+    cache_caps
+        - **jid**: unused
+        - **node**:  unused
+        - **ifrom**: unused
+        - **args**: a ``dict`` containing the verstring and
+          :class:`~.DiscoInfo` payload (
+          ``{'verstring': Optional[str], 'info': Optional[DiscoInfo]}``)
+
+        Cache a verification string with its payload.
+
+    get_caps
+        - **jid**: JID to retrieve the verstring for (unused with the default
+          handler)
+        - **node**:  unused
+        - **ifrom**: unused
+        - **args**: a ``dict`` containing the verstring
+          ``{'verstring': str}``
+        - **returns**: The :class:`~.DiscoInfo` payload for that verstring.
+
+        Get a disco payload from a verstring.
+
+    assign_verstring
+        - **jid**: :class:`~.JID` (full) to assign the verstring to
+        - **node**:  unused
+        - **ifrom**: unused
+        - **args**: a ``dict`` containing the verstring
+          ``{'verstring': str}``
+
+        Cache JID→verstring information.
+
+    get_verstring
+        - **jid**: :class:`~.JID` to use for fetching the verstring
+        - **node**:  unused
+        - **ifrom**: unused
+        - **args**: unused
+        - **returns**: ``str``, the verstring
+
+        Retrieve a verstring for a JID.
 
 Stanza elements
 ---------------
-- 
cgit v1.2.3