From 99fb9ee7f5d5922e9e3dfaf62ed526a4923aab24 Mon Sep 17 00:00:00 2001
From: Joas Schilling <coding@schilljs.com>
Date: Fri, 22 Mar 2024 12:41:56 +0100
Subject: [PATCH] docs(federation): Add a hint which capabilities should be
 used in federation cases

Signed-off-by: Joas Schilling <coding@schilljs.com>
---
 docs/conversation.md              |  3 +++
 lib/Controller/RoomController.php |  3 +++
 openapi-full.json                 |  1 +
 openapi.json                      |  1 +
 src/types/openapi/openapi-full.ts | 10 ++++++++--
 src/types/openapi/openapi.ts      | 10 ++++++++--
 6 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/docs/conversation.md b/docs/conversation.md
index bcb13ce2498..65a38c21bf4 100644
--- a/docs/conversation.md
+++ b/docs/conversation.md
@@ -484,6 +484,9 @@ Get all (for moderators and in case of "free selection") or the assigned breakou
 
 ## Get conversation capabilities
 
+See [Capability handling in federated conversations](https://github.com/nextcloud/spreed/issues/10680) to learn which capabilities
+should be considered from the local server or from the remote server.
+
 * Required capability: `federation-v1`
 * Method: `GET`
 * Endpoint: `/room/{token}/capabilities`
diff --git a/lib/Controller/RoomController.php b/lib/Controller/RoomController.php
index c82d09ebbc7..8882376d26f 100644
--- a/lib/Controller/RoomController.php
+++ b/lib/Controller/RoomController.php
@@ -2239,6 +2239,9 @@ public function setMessageExpiration(int $seconds): DataResponse {
 	/**
 	 * Get capabilities for a room
 	 *
+	 * See "Capability handling in federated conversations" in https://github.com/nextcloud/spreed/issues/10680
+	 * to learn which capabilities should be considered from the local server or from the remote server.
+	 *
 	 * @return DataResponse<Http::STATUS_OK, TalkCapabilities|array<empty>, array{X-Nextcloud-Talk-Hash?: string, X-Nextcloud-Talk-Proxy-Hash?: string}>
 	 *
 	 * 200: Get capabilities successfully
diff --git a/openapi-full.json b/openapi-full.json
index b43018ef755..4343e941cad 100644
--- a/openapi-full.json
+++ b/openapi-full.json
@@ -15300,6 +15300,7 @@
             "get": {
                 "operationId": "room-get-capabilities",
                 "summary": "Get capabilities for a room",
+                "description": "See \"Capability handling in federated conversations\" in https://github.com/nextcloud/spreed/issues/10680 to learn which capabilities should be considered from the local server or from the remote server.",
                 "tags": [
                     "room"
                 ],
diff --git a/openapi.json b/openapi.json
index dafaa2c7c26..8ef8b96d11a 100644
--- a/openapi.json
+++ b/openapi.json
@@ -15410,6 +15410,7 @@
             "get": {
                 "operationId": "room-get-capabilities",
                 "summary": "Get capabilities for a room",
+                "description": "See \"Capability handling in federated conversations\" in https://github.com/nextcloud/spreed/issues/10680 to learn which capabilities should be considered from the local server or from the remote server.",
                 "tags": [
                     "room"
                 ],
diff --git a/src/types/openapi/openapi-full.ts b/src/types/openapi/openapi-full.ts
index 6906320f9f4..b73ad6a821e 100644
--- a/src/types/openapi/openapi-full.ts
+++ b/src/types/openapi/openapi-full.ts
@@ -349,7 +349,10 @@ export type paths = {
     post: operations["room-set-message-expiration"];
   };
   "/ocs/v2.php/apps/spreed/api/{apiVersion}/room/{token}/capabilities": {
-    /** Get capabilities for a room */
+    /**
+     * Get capabilities for a room
+     * @description See "Capability handling in federated conversations" in https://github.com/nextcloud/spreed/issues/10680 to learn which capabilities should be considered from the local server or from the remote server.
+     */
     get: operations["room-get-capabilities"];
   };
   "/ocs/v2.php/apps/spreed/api/{apiVersion}/settings/user": {
@@ -5243,7 +5246,10 @@ export type operations = {
       };
     };
   };
-  /** Get capabilities for a room */
+  /**
+   * Get capabilities for a room
+   * @description See "Capability handling in federated conversations" in https://github.com/nextcloud/spreed/issues/10680 to learn which capabilities should be considered from the local server or from the remote server.
+   */
   "room-get-capabilities": {
     parameters: {
       header: {
diff --git a/src/types/openapi/openapi.ts b/src/types/openapi/openapi.ts
index 52251109bfe..6b1396f2eb6 100644
--- a/src/types/openapi/openapi.ts
+++ b/src/types/openapi/openapi.ts
@@ -353,7 +353,10 @@ export type paths = {
     post: operations["room-set-message-expiration"];
   };
   "/ocs/v2.php/apps/spreed/api/{apiVersion}/room/{token}/capabilities": {
-    /** Get capabilities for a room */
+    /**
+     * Get capabilities for a room
+     * @description See "Capability handling in federated conversations" in https://github.com/nextcloud/spreed/issues/10680 to learn which capabilities should be considered from the local server or from the remote server.
+     */
     get: operations["room-get-capabilities"];
   };
   "/ocs/v2.php/apps/spreed/api/{apiVersion}/settings/user": {
@@ -5144,7 +5147,10 @@ export type operations = {
       };
     };
   };
-  /** Get capabilities for a room */
+  /**
+   * Get capabilities for a room
+   * @description See "Capability handling in federated conversations" in https://github.com/nextcloud/spreed/issues/10680 to learn which capabilities should be considered from the local server or from the remote server.
+   */
   "room-get-capabilities": {
     parameters: {
       header: {