From 5210da0d30ecd17fbb3b04d1620d7e09d35511b0 Mon Sep 17 00:00:00 2001
From: Ken Dreyer <kdreyer@redhat.com>
Date: Feb 07 2020 17:56:48 +0000
Subject: hub: improve search() API documentation


Reformat this text to match Sphinx's conventions. This makes it easier
for developers to read this documentation.

There are a couple small corrections here as well:

- matchType accepts more values than "glob" or "regex", and it treats
  any other value as a plain "=" (strict string match).

- Only globs and regexes are searched insensitively

---

diff --git a/hub/kojihub.py b/hub/kojihub.py
index 5f16026..3231112 100644
--- a/hub/kojihub.py
+++ b/hub/kojihub.py
@@ -12336,13 +12336,27 @@ class RootExports(object):
 
     def search(self, terms, type, matchType, queryOpts=None):
         """Search for an item in the database matching "terms".
-        "type" specifies what object type to search for, and must be
-        one of "package", "build", "tag", "target", "user", "host",
-        "rpm", "maven", or "win".  "matchType" specifies the type of search to
-        perform, and must be one of "glob" or "regexp".  All searches
-        are case-insensitive.  A list of maps containing "id" and
-        "name" will be returned.  If no matches are found, an empty
-        list will be returned."""
+
+        :param str terms: Search for items in the database that match this
+                          value.
+        :param str type: What object type to search for. Must be one of
+                         "package", "build", "tag", "target", "user", "host",
+                         "rpm", "maven", or "win".
+        :param str matchType: The type of search to perform:
+                              - If you specify "glob", Koji will treat "terms"
+                                as a case-insensitive glob.
+                              - If you specify "regexp", Koji will treat
+                                "terms" as a case-insensitive regular
+                                expression.
+                              - Any other value here will cause to Koji to
+                                search for an exact string match for "terms".
+        :param dict queryOpts: Options to pass into the database query. Use
+                               this to limit or order the results of the
+                               search. For example: {'order': 'name'},
+                               or {'limit': 5, 'order': '-build_id'}, etc.
+        :returns: A list of maps containing "id" and "name".  If no matches
+                  are found, this method returns an empty list.
+        """
         if not terms:
             raise koji.GenericError('empty search terms')
         if type == 'file':