added documentation and type hinting

Author: AlexanderWillner

things/api.py

@@ -7,6 +7,7 @@
 import os
 from shlex import quote
 import sys
+from typing import List, Dict
 
 from .database import Database
 
@@ -16,7 +17,7 @@
 # --------------------------------------------------
 
 
-def tasks(uuid=None, include_items=False, **kwargs):
+def tasks(uuid=None, include_items=False, **kwargs):  # noqa: C901
     """
     Read tasks into dicts.
 
@@ -314,8 +315,26 @@ def tags(title=None, include_items=False, **kwargs):
 # Utility API functions derived from above
 # --------------------------------------------------
 
-def search(querystr: str, **kwargs):
-    return tasks(querystr=querystr, **kwargs)
+def search(query: str, **kwargs) -> List[Dict]:
+    """
+    Search the database. This takes mainly notes and titles into account.
+
+    Parameters
+    ----------
+    query : str
+        The string with optional placeholders (%) to search for.
+
+    Returns
+    -------
+    list of dict
+        Representing Things items.
+
+    Examples
+    --------
+    >>> things.search('substring % within notes and titles')
+    ...
+    """
+    return tasks(querystr=query, **kwargs)
 
 
 def get(uuid, default=None, **kwargs):