Some more documentation fixes

Signed-off-by: Joas Schilling <coding@schilljs.com>

developer_manual/digging_deeper/search.rst

@@ -101,6 +101,19 @@ A **search provider** is a class the implements the interface ``\OCP\Search\IPro
             return 'mysearchprovider';
         }
 
+        public function getName(): string {
+            return $this->l->t('My custom group');
+        }
+
+        public function getOrder(string $route, array $routeParameters): int {
+            if (strpos($route, Application::APP_ID . '.') === 0) {
+                // Active app, prefer my results
+                return -1;
+            }
+
+            return 55;
+        }
+
         public function search(IUser $user, ISearchQuery $query): SearchResult {
             return SearchResult::complete(
                 'My custom group', // TODO: this should be translated
@@ -111,7 +124,9 @@ A **search provider** is a class the implements the interface ``\OCP\Search\IPro
         }
     }
 
-The method ``getId`` returns a string idenfier of the registered provider. It has to be globally unique, hence must not conflict with any other apps. Therefore it's advised to use just the app ID (e.g. ``mail``) as ID or an ID that is prefixed with the app id, like ``mail_recipients``.
+The method ``getId`` returns a string identifier of the registered provider. It has to be globally unique, hence must not conflict with any other apps. Therefore it's advised to use just the app ID (e.g. ``mail``) as ID or an ID that is prefixed with the app id, like ``mail_recipients``. ``getName`` is a translated name for your search results.
+
+The ``getOrder`` method returns the order of the provider for the current page. With the route parameter you can check if the route is from your app and in that case use a negative value. Otherwise your app should use a value around 50.
 
 The method ``search`` transforms a search request into a search result.
 
@@ -150,11 +165,11 @@ The provider class is registered via the :ref:`bootstrap mechanism<Bootstrapping
 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 **size limit** of a request and the **cursor** for follow-up request of paginated results.
+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 ``ASearchResultEntry`` objects. ``ASearchResultEntry`` is a static class that has 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. ``SearchResultEntry`` is a static class that can be extended and used by the provider.
 
-.. note:: In most cases you don't have to add any methods or fieds to this new result entry type, 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.
+.. 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
 
@@ -181,6 +196,7 @@ Next, you'll see a dummy provider that returns a static set of results using the
 
     namespace OCA\MyApp\Search;
 
+    use OCA\MyApp\AppInfo\Application;
     use OCP\IL10N;
     use OCP\IURLGenerator;
     use OCP\IUser;
@@ -204,6 +220,19 @@ Next, you'll see a dummy provider that returns a static set of results using the
             return 'mysearchprovider';
         }
 
+        public function getName(): string {
+            return $this->l->t('My app');
+        }
+
+        public function getOrder(string $route, array $routeParameters): int {
+            if (strpos($route, Application::APP_ID . '.') === 0) {
+                // Active app, prefer my results
+                return -1;
+            }
+
+            return 25;
+        }
+
         public function search(IUser $user, ISearchQuery $query): SearchResult {
             return SearchResult::complete(
                 $this->l10n->t('My app'),
@@ -235,6 +264,8 @@ Each of the result result entries has
 * A title, e.g. the name of a file
 * A subline, e.g. the path to a file
 * A resource URL that makes it possible to navigate to the details of this result
+* Optional icon CSS class that is applied then the thumbnail URL was not set
+* A boolean rounded, whether the thumbnail should be rounded, e.g. when it's an avatar
 
 Apps **may** return the full result in ``search``, but in most cases the size of the result set can become too big to fit into one HTTP request and is complicated to display to the user, hence the set should be split into chunks – it should be **paginated**.
 
@@ -255,6 +286,7 @@ For **offset-based pagination** you return ``$query->getLimit()`` results and sp
 
     namespace OCA\MyApp\Search;
 
+    use OCA\MyApp\AppInfo\Application;
     use OCP\IL10N;
     use OCP\IURLGenerator;
     use OCP\IUser;
@@ -278,6 +310,19 @@ For **offset-based pagination** you return ``$query->getLimit()`` results and sp
             return 'mysearchprovider';
         }
 
+        public function getName(): string {
+            return $this->l->t('My app');
+        }
+
+        public function getOrder(string $route, array $routeParameters): int {
+            if (strpos($route, Application::APP_ID . '.') === 0) {
+                // Active app, prefer my results
+                return -1;
+            }
+
+            return 25;
+        }
+
         public function search(IUser $user, ISearchQuery $query): SearchResult {
             $offset = ($query->getCursor() ?? 0);
             $limit = $query->getLimit();
@@ -307,6 +352,7 @@ For a **cursor-based pagination** a app-specific property is used to know a refe
 
     namespace OCA\MyApp\Search;
 
+    use OCA\MyApp\AppInfo\Application;
     use OCP\IL10N;
     use OCP\IURLGenerator;
     use OCP\IUser;
@@ -330,6 +376,19 @@ For a **cursor-based pagination** a app-specific property is used to know a refe
             return 'mysearchprovider';
         }
 
+        public function getName(): string {
+            return $this->l->t('My app');
+        }
+
+        public function getOrder(string $route, array $routeParameters): int {
+            if (strpos($route, Application::APP_ID . '.') === 0) {
+                // Active app, prefer my results
+                return -1;
+            }
+
+            return 25;
+        }
+
         public function search(IUser $user, ISearchQuery $query): SearchResult {
             $cursor = $query->getCursor();
             $limit = $query->getLimit();