Add documentation and improve parameter naming

Signed-off-by: Julius Härtl <jus@bitgrid.net>

4 files changed, 53 insertions, 13 deletions

diff --git a/docs/federated-editing.md b/docs/federated-editing.md
new file mode 100644
index 00000000..9afd57d0
--- /dev/null
+++ b/docs/federated-editing.md
@@ -0,0 +1,16 @@
+# Federated file editing
+
+Collabra Online offers support for collaborative editing of files that are shared through federated
+sharing. The file will always be opened on the file owners instance (Source) and other users will
+connect to that through their Nextcloud instance (Initiator).
+
+In a federated scenario both Nextcloud servers need to add each other as trusted servers or in a
+global scale environment a list of nodes can be added through the `gs.trustedHosts` setting in the
+config.php file.
+
+When a Initiator opens a file that is located on an incoming federated share, a check will be
+performed if the share owners instance supports federated editing. If that is the case a Initiator
+token will be created, and the user will be redirected to the Source instance to open the file.
+
+The source instance will then fetch the user and file details, create a WOPI token for the remote
+user with those details and open the document with that.
diff --git a/docs/mobile_editor.md b/docs/mobile_editor.md
index c0c013ab..193bf7ba 100644
--- a/docs/mobile_editor.md
+++ b/docs/mobile_editor.md
@@ -1,14 +1,40 @@
 # Mobile Editor OCS API
 
-This API is used to obtain a link for a document to load from mobile apps
+This API is used to obtain a link for a document to load from mobile apps. The link will contain a
+one-time token that can be used once for opening a document in an anonymous browser session or
+webview on mobile devices in the context of the user.
 
-## Creating the link
+## Creating a link for a local file
 
 ```
 <server>/ocs/v2.php/apps/richdocuments/api/v1/document
 ```
 
-A `POST` request to this endpoint with the `fileid` parameter will
-preprare the server to serve this document.
+A `POST` request to this endpoint with the `fileid` parameter will preprare the server to serve this
+document.
+
+The returned xml or json will have an url to open in a webview.
+
+## Creating a link for public share links
+
+Opening public share links requires federated editing being properly setup between the two servers.
+
+```
+<server>/ocs/v2.php/apps/richdocuments/api/v1/share
+```
+
+A `POST` request to this endpoint with the following parameters preprare the server to serve this
+document:
+
+| Parameter | Type | Description | Example |
+|---|---|---|---|
+| shareToken | string | Share token of the public share link | Qf5toz6JD7Tn7eD |
+| host | string (optional) | Desc | http://cloud.example.com |
+| path | string (optional) | Path to the file in case the share link is a directory | /path/to/file.odt |
+| password | string (optional) | Optional password to gain access to the share | secret |
+
+The returned xml or json will have an url to open in a webview.
+
+The user will join the session as a guest but with their user details provided by their own
+instance.
 
-The returned xml or json will has an url to open in a webview.
diff --git a/lib/Controller/OCSController.php b/lib/Controller/OCSController.php
index c7cf7520..3294ea67 100644
--- a/lib/Controller/OCSController.php
+++ b/lib/Controller/OCSController.php
@@ -128,27 +128,25 @@ class OCSController extends \OCP\AppFramework\OCSController {
 	/**
 	 * Generate a direct editing link for a file in a public share to open with the current user
 	 *
-	 * If
-	 *
 	 * @NoAdminRequired
 	 * @throws OCSForbiddenException
 	 */
 	public function createPublic(
-		string $shareTokenSourceInstance = null,
 		string $shareToken,
+		string $host = null,
 		string $path = '',
 		string $password = null
 	): DataResponse {
-		if ($shareTokenSourceInstance) {
-			$remoteCollabora = $this->federationService->getRemoteCollaboraURL($shareTokenSourceInstance);
+		if ($host) {
+			$remoteCollabora = $this->federationService->getRemoteCollaboraURL($host);
 			if ($remoteCollabora === '') {
 				throw new OCSNotFoundException('Failed to connect to remote collabora instance.');
 			}
 
-			$wopi = $this->tokenManager->newInitiatorToken($shareTokenSourceInstance, null, $shareToken, true, $this->userId);
+			$wopi = $this->tokenManager->newInitiatorToken($host, null, $shareToken, true, $this->userId);
 
 			$client = \OC::$server->getHTTPClientService()->newClient();
-			$response = $client->post(rtrim($shareTokenSourceInstance, '/') . '/ocs/v2.php/apps/richdocuments/api/v1/direct/share/initiator?format=json', [
+			$response = $client->post(rtrim($host, '/') . '/ocs/v2.php/apps/richdocuments/api/v1/direct/share/initiator?format=json', [
 				'body' => [
 					'initiatorServer' => \OC::$server->getURLGenerator()->getAbsoluteURL(''),
 					'initiatorToken' => $wopi->getToken(),
diff --git a/tests/features/bootstrap/DirectContext.php b/tests/features/bootstrap/DirectContext.php
index c9c4a57d..4c17a0f4 100644
--- a/tests/features/bootstrap/DirectContext.php
+++ b/tests/features/bootstrap/DirectContext.php
@@ -154,7 +154,7 @@ class DirectContext implements Context {
 
 	private function requestPublicDirectEditingLink($user, $token, $filePath = null, $password = null) {
 		$this->serverContext->sendOCSRequest('POST', 'apps/richdocuments/api/v1/share', [
-			'shareTokenSourceInstance' => $this->serverContext->getBaseUrl(),
+			'host' => $this->serverContext->getBaseUrl(),
 			'shareToken' => $token,
 			'path' => $filePath,
 			'password' => $password