From 28485c80063fa0bf520c7c84b32be0a6caf8cdff Mon Sep 17 00:00:00 2001
From: Christoph Wurst <christoph@winzerhof-wurst.at>
Date: Fri, 4 Dec 2020 08:49:54 +0100
Subject: [PATCH 1/2] Fix outdated unified search result entry class suggestion

Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>
---
 developer_manual/digging_deeper/search.rst | 24 ++++------------------
 1 file changed, 4 insertions(+), 20 deletions(-)

diff --git a/developer_manual/digging_deeper/search.rst b/developer_manual/digging_deeper/search.rst
index d8534b19bce..5979db34835 100644
--- a/developer_manual/digging_deeper/search.rst
+++ b/developer_manual/digging_deeper/search.rst
@@ -168,26 +168,9 @@ Handling search requests
 
 Search requests are processed in the ``search`` method. The ``$user`` object is the user who the result shall be generated for. ``$query`` gives context information like the **search term**, the **sort order**, the **route information**, the **size limit** of a request and the **cursor** for follow-up request of paginated results.
 
-The result is encapsulated in the ``SearchResult`` class that offers two static factory methods ``complete`` and ``paginated``. Both of these methods take an array of ``SearchResultEntry`` objects. ``SearchResultEntry`` is a static class that can be extended and used by the provider.
+The result is encapsulated in the ``SearchResult`` class that offers two static factory methods ``complete`` and ``paginated``. Both of these methods take an array of ``SearchResultEntry`` objects.
 
-.. note:: In most cases you don't have to add any methods or fields to this new result entry type so you can directly use ``SearchResultEntry``, but this API design was chosen so new optional properties can be added in the future without breaking the existing implementations in 3rd party apps.
-
-.. code-block:: php
-
-    <?php
-
-    declare(strict_types=1);
-
-    namespace OCA\MyApp\Search;
-
-    use OCP\Search\SearchResultEntry;
-
-    class MySearchResultEntry extends SearchResultEntry {}
-
-
-The above snippet shows this implementation of a result entry. Again, this class should be saved to ``lib/Search`` in the app directory.
-
-Next, you'll see a dummy provider that returns a static set of results using the result entry class from above.
+Next, you'll see a dummy provider that returns a static set of results.
 
 .. code-block:: php
 
@@ -202,6 +185,7 @@ Next, you'll see a dummy provider that returns a static set of results using the
     use OCP\IURLGenerator;
     use OCP\IUser;
     use OCP\Search\IProvider;
+    use OCP\Search\SearchResultEntry;
 
     class Provider implements IProvider {
 
@@ -238,7 +222,7 @@ Next, you'll see a dummy provider that returns a static set of results using the
             return SearchResult::complete(
                 $this->l10n->t('My app'),
                 [
-                    new MySearchResultEntry(
+                    new SearchResultEntry(
                         $this->urlGenerator->linkToRoute(
                             'myapp.Preview.getPreviewByFileId',
                             [

From 09dac2fdd0d0a27084d89a7e4b22be3494bfcff8 Mon Sep 17 00:00:00 2001
From: Christoph Wurst <christoph@winzerhof-wurst.at>
Date: Fri, 4 Dec 2020 09:12:29 +0100
Subject: [PATCH 2/2] Document optional unified search result entry attributes

Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>
---
 .../upgrade-guide.rst                          |  2 +-
 developer_manual/digging_deeper/search.rst     | 18 ++++++++++++++++++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/developer_manual/app_publishing_maintenance/upgrade-guide.rst b/developer_manual/app_publishing_maintenance/upgrade-guide.rst
index ee75f32802d..e28cd8bb5be 100644
--- a/developer_manual/app_publishing_maintenance/upgrade-guide.rst
+++ b/developer_manual/app_publishing_maintenance/upgrade-guide.rst
@@ -40,7 +40,7 @@ jQuery was updated to v2.2. The most notable change is that ``$(document).ready(
 Search
 ******
 
-The unified search replaces the traditional search input, hence ``OCA.Search`` became a noop. For backwards compatibility, the code will not raise any errors now, but it does not have any functionality.
+The :ref:`unified search<unified-search>` replaces the traditional search input, hence ``OCA.Search`` became a noop. For backwards compatibility, the code will not raise any errors now, but it does not have any functionality.
 
 Removed globals
 ***************
diff --git a/developer_manual/digging_deeper/search.rst b/developer_manual/digging_deeper/search.rst
index 5979db34835..17fbdb7a943 100644
--- a/developer_manual/digging_deeper/search.rst
+++ b/developer_manual/digging_deeper/search.rst
@@ -1,3 +1,5 @@
+.. _unified-search:
+
 ======
 Search
 ======
@@ -394,3 +396,19 @@ For a **cursor-based pagination** a app-specific property is used to know a refe
             );
         }
     }
+
+Optional attributes
+^^^^^^^^^^^^^^^^^^^
+
+The unified search is available via OCS, which means client application like the mobile apps can use it to get access to the server search mechanism. The default properties of a search result entry might be difficult to parse and interpret in those clients, hence it's possible to add optional string attributes to each entry.
+
+.. code-block:: php
+
+    <?php
+
+    $entry = new SearchResultEntry(/* same arguments as above */);
+    $entry->addAttribute("type", "deckCard");
+    $entry->addAttribute("cardId", "1234");
+    $entry->addAttribute("boardId", "567");
+
+.. note:: This method was added in Nextcloud 21. If your app also targets Nextcloud 20 you should either not use it or add a version check to invoke the method only conditionally.